vsm 0.0.1 → 0.2.0

data/lib/vsm/ports/mcp/server_stdio.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+require "json"
+require "async"
+
+module VSM
+  module Ports
+    module MCP
+      # Exposes the capsule's tools as an MCP server over stdio (NDJSON JSON-RPC).
+      # Implemented methods: tools/list, tools/call.
+      class ServerStdio < VSM::Port
+        def initialize(capsule:)
+          super(capsule: capsule)
+          @waiters = {}
+          @waiters_mutex = Mutex.new
+        end
+
+        def egress_subscribe
+          # Single subscriber that resolves tool_result waiters by corr_id
+          @capsule.bus.subscribe do |m|
+            next unless m.kind == :tool_result
+            q = nil
+            @waiters_mutex.synchronize { q = @waiters.delete(m.corr_id.to_s) }
+            q&.enqueue(m)
+          end
+          super
+        end
+
+        def loop
+          $stdout.sync = true
+          while (line = $stdin.gets)
+            begin
+              req = JSON.parse(line)
+            rescue => e
+              write_err(nil, code: -32700, message: "Parse error: #{e.message}")
+              next
+            end
+
+            id = req["id"]
+            method = req["method"]
+            params = req["params"] || {}
+            case method
+            when "tools/list"
+              write_ok(id, { tools: list_tools })
+            when "tools/call"
+              name = params["name"].to_s
+              args = params["arguments"] || {}
+              res = call_local_tool(id, name, args)
+              write_ok(id, { content: [{ type: "text", text: res.to_s }] })
+            else
+              write_err(id, code: -32601, message: "Method not found: #{method}")
+            end
+          end
+        end
+
+        private
+
+        def list_tools
+          ops = @capsule.bus.context[:operations_children] || {}
+          ops.values
+             .select { _1.respond_to?(:tool_descriptor) }
+             .map { to_mcp_descriptor(_1.tool_descriptor) }
+        end
+
+        def to_mcp_descriptor(desc)
+          {
+            "name" => desc.name,
+            "description" => desc.description,
+            "input_schema" => desc.schema
+          }
+        end
+
+        def call_local_tool(req_id, name, args)
+          corr = req_id.to_s
+          q = Async::Queue.new
+          @waiters_mutex.synchronize { @waiters[corr] = q }
+          @capsule.bus.emit VSM::Message.new(
+            kind: :tool_call,
+            payload: { tool: name, args: args },
+            corr_id: corr,
+            meta: { session_id: "mcp:stdio" },
+            path: [:mcp, :server, name]
+          )
+          msg = q.dequeue
+          msg.payload
+        ensure
+          @waiters_mutex.synchronize { @waiters.delete(corr) }
+        end
+
+        def write_ok(id, result)
+          puts JSON.dump({ jsonrpc: "2.0", id: id, result: result })
+          $stdout.flush
+        end
+
+        def write_err(id, code:, message:)
+          puts JSON.dump({ jsonrpc: "2.0", id: id, error: { code: code, message: message } })
+          $stdout.flush
+        end
+      end
+    end
+  end
+end

data/lib/vsm/roles/coordination.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+module VSM
+  class Coordination
+    def initialize
+      @queue = []
+      @floor_by_session = nil
+      @turn_waiters = {} # session_id => Async::Queue
+    end
+
+    def observe(bus)
+      # Note: staging is handled by the capsule loop, not by subscription
+      # This method exists for consistency but doesn't auto-stage messages
+    end
+
+    def stage(message) = (@queue << message)
+
+    def drain(bus)
+      return if @queue.empty?
+      @queue.sort_by! { order(_1) }
+      @queue.shift(@queue.size).each do |msg|
+        yield msg
+        if msg.kind == :assistant && (sid = msg.meta&.dig(:session_id)) && @turn_waiters[sid]
+          @turn_waiters[sid].enqueue(:done)
+        end
+      end
+    end
+
+    def grant_floor!(session_id) = (@floor_by_session = session_id)
+
+    def wait_for_turn_end(session_id)
+      q = (@turn_waiters[session_id] ||= Async::Queue.new)
+      q.dequeue
+    end
+
+    def order(m)
+      base =
+        case m.kind
+        when :user            then 0
+        when :tool_result     then 1
+        when :plan            then 2
+        when :assistant_delta then 3
+        when :assistant       then 4
+        else 9
+        end
+      sid = m.meta&.dig(:session_id)
+      sid == @floor_by_session ? base - 1 : base
+    end
+  end
+end

data/lib/vsm/roles/governance.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+module VSM
+  class Governance
+    def observe(bus); end
+    def enforce(message)
+      yield message
+    end
+  end
+end

data/lib/vsm/roles/identity.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+module VSM
+  class Identity
+    def initialize(identity:, invariants: [])
+      @identity, @invariants = identity, invariants
+    end
+    def observe(bus); end
+    def handle(message, bus:, **) = false
+    def alert(message); end
+  end
+end

data/lib/vsm/roles/intelligence.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+require "set"
+require_relative "../drivers/family"
+
+module VSM
+  # Orchestrates multi-turn LLM chat with native tool-calls:
+  # - Maintains neutral conversation history per session_id
+  # - Talks to a provider driver that yields :assistant_delta, :assistant_final, :tool_calls
+  # - Emits :tool_call to Operations, waits for ALL results, then continues
+  #
+  # App authors can subclass and only customize:
+  #   - system_prompt(session_id) -> String
+  #   - offer_tools?(session_id, descriptor) -> true/false (filter tools)
+  class Intelligence
+    attr_reader :driver
+
+    def initialize(driver: nil, system_prompt: nil)
+      @driver         = driver
+      @system_prompt  = system_prompt
+      @sessions       = Hash.new { |h,k| h[k] = new_session_state }
+    end
+
+    def observe(bus); end
+
+    def handle(message, bus:, **)
+      # If no driver is configured, the base implementation is inert.
+      # Subclasses can override #handle to implement non-LLM behavior.
+      return false if @driver.nil?
+      case message.kind
+      when :user
+        sid = message.meta&.dig(:session_id)
+        st  = state(sid)
+        st[:history] << { role: "user", content: message.payload.to_s }
+        invoke_model(sid, bus)
+        true
+
+      when :tool_result
+        sid = message.meta&.dig(:session_id)
+        st  = state(sid)
+        # map id -> tool name if we learned it earlier (useful for Gemini)
+        name = st[:tool_id_to_name][message.corr_id]
+        
+        # Debug logging
+        if ENV["VSM_DEBUG_STREAM"] == "1"
+          $stderr.puts "Intelligence: Received tool_result for #{name}(#{message.corr_id}): #{message.payload.to_s.slice(0, 100)}"
+        end
+        
+        st[:history] << { role: "tool_result", tool_call_id: message.corr_id, name: name, content: message.payload.to_s }
+        st[:pending_tool_ids].delete(message.corr_id)
+        # Only continue once all tool results for this turn arrived:
+        if st[:pending_tool_ids].empty?
+          # Re-enter model for the same turn with tool results in history:
+          invoke_model(sid, bus)
+        end
+        true
+
+      else
+        false
+      end
+    end
+
+    # --- Extension points for apps ---
+
+    # Override to compute a dynamic prompt per session
+    def system_prompt(session_id)
+      @system_prompt
+    end
+
+    # Override to filter tools the model may use (by descriptor)
+    def offer_tools?(session_id, descriptor)
+      true
+    end
+
+    private
+
+    def new_session_state
+      {
+        history: [],
+        pending_tool_ids: Set.new,
+        tool_id_to_name: {},
+        inflight: false,
+        turn_seq: 0
+      }
+    end
+
+    def state(sid) = @sessions[sid]
+
+    def invoke_model(session_id, bus)
+      st = state(session_id)
+      if st[:inflight] || !st[:pending_tool_ids].empty?
+        if ENV["VSM_DEBUG_STREAM"] == "1"
+          $stderr.puts "Intelligence: skip invoke sid=#{session_id} inflight=#{st[:inflight]} pending=#{st[:pending_tool_ids].size}"
+        end
+        return
+      end
+      st[:inflight] = true
+      st[:turn_seq] += 1
+      current_turn_id = st[:turn_seq]
+
+      # Discover tools available from Operations children:
+      descriptors, name_index = tool_inventory(bus, session_id)
+
+      # Debug logging
+      if ENV["VSM_DEBUG_STREAM"] == "1"
+        $stderr.puts "Intelligence: invoke_model sid=#{session_id} inflight=#{st[:inflight]} pending=#{st[:pending_tool_ids].size} turn_seq=#{st[:turn_seq]}"
+        $stderr.puts "Intelligence: Calling driver with #{st[:history].size} history entries"
+        st[:history].each_with_index do |h, i|
+          $stderr.puts "  [#{i}] #{h[:role]}: #{h[:role] == 'assistant_tool_calls' ? h[:tool_calls].map{|tc| "#{tc[:name]}(#{tc[:id]})"}.join(', ') : h[:content]&.slice(0, 100)}"
+        end
+      end
+
+      task = Async do
+        begin
+          @driver.run!(
+            conversation: st[:history],
+            tools: descriptors,
+            policy: { system_prompt: system_prompt(session_id) }
+          ) do |event, payload|
+            case event
+            when :assistant_delta
+              # optionally buffer based on stream_policy
+              bus.emit VSM::Message.new(kind: :assistant_delta, payload: payload, meta: { session_id: session_id, turn_id: current_turn_id })
+            when :assistant_final
+              unless payload.to_s.empty?
+                st[:history] << { role: "assistant", content: payload.to_s }
+              end
+              bus.emit VSM::Message.new(kind: :assistant, payload: payload, meta: { session_id: session_id, turn_id: current_turn_id })
+            when :tool_calls
+              st[:history] << { role: "assistant_tool_calls", tool_calls: payload }
+              st[:pending_tool_ids] = Set.new(payload.map { _1[:id] })
+              payload.each { |c| st[:tool_id_to_name][c[:id]] = c[:name] }
+              if ENV["VSM_DEBUG_STREAM"] == "1"
+                $stderr.puts "Intelligence: tool_calls count=#{payload.size}; pending now=#{st[:pending_tool_ids].size}"
+              end
+              # Allow next invocation (after tools complete) without waiting for driver ensure
+              st[:inflight] = false
+              payload.each do |call|
+                bus.emit VSM::Message.new(
+                  kind: :tool_call,
+                  payload: { tool: call[:name], args: call[:arguments] },
+                  corr_id: call[:id],
+                  meta: { session_id: session_id, tool: call[:name], turn_id: current_turn_id }
+                )
+              end
+            end
+          end
+        ensure
+          if ENV["VSM_DEBUG_STREAM"] == "1"
+            $stderr.puts "Intelligence: driver completed sid=#{session_id}; pending=#{st[:pending_tool_ids].size}; inflight->false"
+          end
+          st[:inflight] = false
+        end
+      end
+      st[:task] = task
+    end
+
+    # Return [descriptors:Array<VSM::Tool::Descriptor>, index Hash{name=>capsule}]
+    def tool_inventory(bus, session_id)
+      ops = bus.context[:operations_children] || {}
+      descriptors = []
+      index = {}
+      ops.each do |name, capsule|
+        next unless capsule.respond_to?(:tool_descriptor)
+        desc = capsule.tool_descriptor
+        next unless offer_tools?(session_id, desc)
+        descriptors << desc
+        index[desc.name] = capsule
+      end
+      [descriptors, index]
+    end
+  end
+end

data/lib/vsm/roles/operations.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../executors/fiber_executor"
+require_relative "../executors/thread_executor"
+
+module VSM
+  class Operations
+    EXECUTORS = {
+      fiber:  Executors::FiberExecutor,
+      thread: Executors::ThreadExecutor
+    }.freeze
+
+    def observe(bus); end
+
+    def handle(message, bus:, children:, **)
+      return false unless message.kind == :tool_call
+
+      name = message.payload[:tool].to_s
+      tool_capsule = children.fetch(name) { raise "unknown tool capsule: #{name}" }
+      mode = tool_capsule.respond_to?(:execution_mode) ? tool_capsule.execution_mode : :fiber
+      executor = EXECUTORS.fetch(mode)
+
+      Async do
+        result = executor.call(tool_capsule, message.payload[:args])
+        bus.emit Message.new(kind: :tool_result, payload: result, corr_id: message.corr_id, meta: message.meta)
+      rescue => e
+        bus.emit Message.new(kind: :tool_result, payload: "ERROR: #{e.class}: #{e.message}", corr_id: message.corr_id, meta: message.meta)
+      end
+
+      true
+    end
+  end
+end

data/lib/vsm/runtime.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+require "async"
+
+module VSM
+  module Runtime
+    def self.start(capsule, ports: [])
+      Async do |task|
+        capsule.run
+        ports.each do |p|
+          p.egress_subscribe if p.respond_to?(:egress_subscribe)
+          task.async { p.loop } if p.respond_to?(:loop)
+        end
+        task.sleep
+      end
+    end
+  end
+end
+

data/lib/vsm/tool/acts_as_tool.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+module VSM
+  module ActsAsTool
+    def self.included(base) = base.extend(ClassMethods)
+
+    module ClassMethods
+      def tool_name(value = nil);  @tool_name = value if value; @tool_name; end
+      def tool_description(value = nil); @tool_description = value if value; @tool_description; end
+      def tool_schema(value = nil); @tool_schema = value if value; @tool_schema; end
+    end
+
+    def tool_descriptor
+      VSM::Tool::Descriptor.new(
+        name: self.class.tool_name,
+        description: self.class.tool_description,
+        schema: self.class.tool_schema
+      )
+    end
+  end
+end

data/lib/vsm/tool/capsule.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module VSM
+  class ToolCapsule
+    include ActsAsTool
+    attr_writer :governance
+    def governance = @governance || (raise "governance not injected")
+    # Subclasses implement:
+    # def run(args) ... end
+    # Optional:
+    # def execution_mode = :fiber | :thread
+  end
+end

data/lib/vsm/tool/descriptor.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+module VSM
+  module Tool
+    Descriptor = Struct.new(:name, :description, :schema, keyword_init: true) do
+      def to_openai_tool
+        { type: "function", function: { name:, description:, parameters: schema } }
+      end
+      def to_anthropic_tool
+        { name:, description:, input_schema: schema }
+      end
+      def to_gemini_tool
+        { name:, description:, parameters: schema }
+      end
+    end
+  end
+end

data/lib/vsm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vsm
-  VERSION = "0.0.1"
+  VERSION = "0.2.0"
 end

data/lib/vsm.rb

@@ -1,7 +1,50 @@
 # frozen_string_literal: true
 
+require "async"
+require "async/queue"
+
 require_relative "vsm/version"
 
+require_relative "vsm/message"
+require_relative "vsm/async_channel"
+require_relative "vsm/homeostat"
+require_relative "vsm/observability/ledger"
+
+require_relative "vsm/roles/operations"
+require_relative "vsm/roles/coordination"
+require_relative "vsm/roles/intelligence"
+require_relative "vsm/roles/governance"
+require_relative "vsm/roles/identity"
+
+require_relative "vsm/tool/descriptor"
+require_relative "vsm/tool/acts_as_tool"
+require_relative "vsm/tool/capsule"
+
+require_relative "vsm/meta"
+
+require_relative "vsm/executors/fiber_executor"
+require_relative "vsm/executors/thread_executor"
+
+require_relative "vsm/capsule"
+require_relative "vsm/dsl"
+require_relative "vsm/port"
+require_relative "vsm/runtime"
+
+require_relative "vsm/drivers/openai/async_driver"
+require_relative "vsm/drivers/anthropic/async_driver"
+require_relative "vsm/drivers/gemini/async_driver"
+require_relative "vsm/drivers/family"
+
+require_relative "vsm/lens"
+
+# Optional/built-in ports and MCP integration
+require_relative "vsm/ports/chat_tty"
+require_relative "vsm/ports/mcp/server_stdio"
+require_relative "vsm/mcp/jsonrpc"
+require_relative "vsm/mcp/client"
+require_relative "vsm/mcp/remote_tool_capsule"
+require_relative "vsm/dsl_mcp"
+
 module Vsm
   class Error < StandardError; end
   # Your code goes here...