kairos-chain 3.9.0 → 3.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4facdf3bcb070b304f05d2ba2edd1d115e2f743db24c47864d953280da4c80f0
-  data.tar.gz: debbc87b1676e18e7a3ff200132d956ac8531324aecbf957e625fc6e8cdab059
+  metadata.gz: 21836fb01fd3a42cad85b2976517109e825e2bb0bbd3b096ef02a814a48a61ea
+  data.tar.gz: 73d3c52a49d34ccc58b7ee843492ce862cec3107f705e04c5a41af0640e210fd
 SHA512:
-  metadata.gz: af08ba6ddefba694090ca8f989b215ae80e2417e794ad3f3ece1bfb8b73e8aa428c1ea636e2ad9278a268b6f95435a180c043a96db15293e2f3351c2c2efc10b
-  data.tar.gz: c4d15cc38e425154e64cfd5aa52c80c939c3f00ce4ed8d0036c12e282816c0f320dae27bac46df968a8c74d1ac926037b0883244b7ed64827ff16dec18cc4c84
+  metadata.gz: 4a0da1ccb68ebec0a33fd79be6ddf16da004191d46759eab8f940a0c3ba5c687771ddcc472e164fcd688a9c2e94e657f948eb34dfbb403de970c797add85e87a
+  data.tar.gz: ff56f6cdea6087a5e9885037f86442941069abd96bbdc01006f193ea6aee4ed0fa8012f0a6224f3d958b333e14fada684fd8e6d5b31be7cdddcc11e03c3bd067

data/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.9.1] - 2026-03-30
+
+### Fixed
+
+- **llm_client SkillSet missing from gem templates** — `llm_client` files existed
+  only in the project-root `templates/` but not in the gem-bundled
+  `KairosChain_mcp_server/templates/skillsets/llm_client/`. This caused
+  `llm_call`, `llm_configure`, and `llm_status` tools to be unavailable on
+  fresh installs, breaking the `agent` SkillSet (`depends_on: ["llm_client"]`).
+
 ## [3.9.0] - 2026-03-30
 
 ### Added

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.9.0"
+  VERSION = "3.9.1"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/llm_client/llm_call.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+require 'time'
+require_relative '../lib/llm_client/adapter'
+require_relative '../lib/llm_client/anthropic_adapter'
+require_relative '../lib/llm_client/openai_adapter'
+require_relative '../lib/llm_client/claude_code_adapter'
+require_relative '../lib/llm_client/bedrock_adapter'
+require_relative '../lib/llm_client/schema_converter'
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      module Tools
+        class LlmCall < KairosMcp::Tools::BaseTool
+          def name
+            'llm_call'
+          end
+
+          def description
+            'Make exactly one LLM API call. Returns response including tool_use requests. ' \
+              'Does NOT execute tools, loop, retry, or fall back. Pure transport.'
+          end
+
+          def category
+            :llm
+          end
+
+          def usecase_tags
+            %w[llm api call provider transport]
+          end
+
+          def related_tools
+            %w[llm_configure llm_status]
+          end
+
+          def input_schema
+            {
+              type: 'object',
+              properties: {
+                messages: {
+                  type: 'array',
+                  description: 'Conversation messages array (role + content)',
+                  items: { type: 'object' }
+                },
+                system: {
+                  type: 'string',
+                  description: 'System prompt (optional)'
+                },
+                tools: {
+                  type: 'array',
+                  description: 'Tool names or fnmatch patterns to include as LLM tools (optional)',
+                  items: { type: 'string' }
+                },
+                invocation_context_json: {
+                  type: 'string',
+                  description: 'Serialized InvocationContext for policy-filtered schema discovery (optional)'
+                },
+                model: {
+                  type: 'string',
+                  description: 'Model override (optional, uses config default)'
+                },
+                max_tokens: {
+                  type: 'integer',
+                  description: 'Max tokens override (optional)'
+                },
+                temperature: {
+                  type: 'number',
+                  description: 'Temperature override (optional)'
+                }
+              },
+              required: ['messages']
+            }
+          end
+
+          def call(arguments)
+            config = load_config
+            adapter = build_adapter(config)
+            messages = arguments['messages']
+            system = arguments['system']
+            model = arguments['model']
+            max_tokens = arguments['max_tokens']
+            temperature = arguments['temperature']
+
+            # Resolve tool schemas with policy filtering
+            tool_schemas = nil
+            tool_names_provided = []
+            if arguments['tools'] && !arguments['tools'].empty?
+              ctx = deserialize_context(arguments['invocation_context_json'])
+              tool_schemas, tool_names_provided = resolve_and_convert_tools(
+                arguments['tools'], ctx, config
+              )
+            end
+
+            # Make the API call
+            raw_response = adapter.call(
+              messages: messages,
+              system: system,
+              tools: tool_schemas,
+              model: model,
+              max_tokens: max_tokens,
+              temperature: temperature
+            )
+
+            # Track usage
+            usage = extract_usage(raw_response, adapter)
+
+            # Build success payload
+            actual_model = raw_response['model'] || model || config['model'] || 'unknown'
+            payload = {
+              'status' => 'ok',
+              'provider' => config['provider'],
+              'model' => actual_model,
+              'response' => raw_response,
+              'usage' => usage,
+              'snapshot' => build_snapshot(
+                actual_model, system, messages, tool_names_provided, raw_response
+              )
+            }
+
+            UsageTracker.record(usage)
+            text_content(JSON.generate(payload))
+          rescue KairosMcp::SkillSets::LlmClient::ApiError => e
+            text_content(JSON.generate({
+              'status' => 'error',
+              'error' => {
+                'type' => e.is_a?(AuthError) ? 'auth_error' : 'api_error',
+                'message' => e.message,
+                'provider' => e.provider,
+                'retryable' => e.retryable,
+                'rate_limited' => e.rate_limited,
+                'suggested_backoff_seconds' => e.suggested_backoff
+              }
+            }))
+          rescue StandardError => e
+            text_content(JSON.generate({
+              'status' => 'error',
+              'error' => {
+                'type' => classify_error(e),
+                'message' => e.message,
+                'provider' => nil,
+                'retryable' => false,
+                'rate_limited' => false,
+                'suggested_backoff_seconds' => nil
+              }
+            }))
+          end
+
+          private
+
+          def load_config
+            config_path = File.join(__dir__, '..', 'config', 'llm_client.yml')
+            if File.exist?(config_path)
+              require 'yaml'
+              YAML.safe_load(File.read(config_path), permitted_classes: [Symbol]) || {}
+            else
+              { 'provider' => 'anthropic', 'model' => 'claude-sonnet-4-6',
+                'api_key_env' => 'ANTHROPIC_API_KEY' }
+            end
+          end
+
+          def build_adapter(config)
+            case config['provider']
+            when 'openai', 'local', 'openrouter'
+              OpenaiAdapter.new(config)
+            when 'claude_code'
+              ClaudeCodeAdapter.new(config)
+            when 'bedrock'
+              BedrockAdapter.new(config)
+            else
+              AnthropicAdapter.new(config)
+            end
+          end
+
+          def deserialize_context(json_string)
+            return nil if json_string.nil? || json_string.empty?
+
+            ctx = KairosMcp::InvocationContext.from_json(json_string)
+            return ctx if ctx
+
+            # Fail-closed: malformed context returns a deny-all context
+            KairosMcp::InvocationContext.new(whitelist: [])
+          rescue StandardError
+            # Parse error → deny-all (fail-closed, not fail-open)
+            KairosMcp::InvocationContext.new(whitelist: [])
+          end
+
+          def resolve_and_convert_tools(patterns, invocation_context, config)
+            return [nil, []] unless @registry
+
+            all_schemas = @registry.list_tools
+
+            # Expand fnmatch patterns
+            resolved = all_schemas.select { |s|
+              patterns.any? { |pat| File.fnmatch(pat, s[:name]) }
+            }
+
+            # Policy filter: only include tools the context allows
+            if invocation_context
+              resolved = resolved.select { |s| invocation_context.allowed?(s[:name]) }
+            end
+
+            tool_names = resolved.map { |s| s[:name] }
+
+            # Convert to provider format
+            target = config['provider'] == 'openai' ? :openai : :anthropic
+            result = SchemaConverter.convert_batch(resolved, target)
+
+            unless result[:errors].empty?
+              warn "[llm_call] Schema conversion errors: #{result[:errors].map { |e| e[:tool] }.join(', ')}"
+            end
+
+            [result[:schemas], tool_names]
+          end
+
+          def extract_usage(response, adapter)
+            input_t = response.delete('input_tokens').to_i
+            output_t = response.delete('output_tokens').to_i
+            {
+              'input_tokens' => input_t,
+              'output_tokens' => output_t,
+              'total_tokens' => input_t + output_t
+            }
+          end
+
+          def build_snapshot(model, system, messages, tool_names, response)
+            {
+              'timestamp' => Time.now.iso8601,
+              'model' => model,
+              'system_prompt_hash' => system ? Digest::SHA256.hexdigest(system)[0..15] : nil,
+              'messages_count' => messages&.length || 0,
+              'tool_schemas_provided' => tool_names,
+              'response_summary_length' => (response['content'] || '').length
+            }
+          end
+
+          def classify_error(error)
+            case error
+            when JSON::ParserError then 'parse_error'
+            when Errno::ENOENT, Errno::EACCES then 'config_error'
+            else 'api_error'
+            end
+          end
+        end
+
+        # In-memory usage tracker (per ToolRegistry lifecycle)
+        module UsageTracker
+          @mutex = Mutex.new
+          @stats = { calls: 0, input_tokens: 0, output_tokens: 0 }
+
+          def self.record(usage)
+            @mutex.synchronize do
+              @stats[:calls] += 1
+              @stats[:input_tokens] += usage['input_tokens'].to_i
+              @stats[:output_tokens] += usage['output_tokens'].to_i
+            end
+          end
+
+          def self.stats
+            @mutex.synchronize { @stats.dup }
+          end
+
+          def self.reset!
+            @mutex.synchronize { @stats = { calls: 0, input_tokens: 0, output_tokens: 0 } }
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/llm_client/adapter.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      # Abstract LLM provider adapter. Subclasses implement #call.
+      class Adapter
+        attr_reader :config
+
+        def initialize(config)
+          @config = config
+        end
+
+        # Make one API call. Returns normalized response hash.
+        # Subclasses MUST rescue provider errors and raise ApiError.
+        def call(messages:, system: nil, tools: nil, model: nil,
+                 max_tokens: nil, temperature: nil)
+          raise NotImplementedError, "#{self.class}#call not implemented"
+        end
+
+        protected
+
+        def resolve_model(override)
+          override || @config['model'] || @config[:model]
+        end
+
+        def resolve_max_tokens(override)
+          override || @config['default_max_tokens'] || @config[:default_max_tokens] || 4096
+        end
+
+        def resolve_temperature(override)
+          override || @config['default_temperature'] || @config[:default_temperature] || 0.7
+        end
+
+        def resolve_api_key
+          env_var = @config['api_key_env'] || @config[:api_key_env]
+          raise AuthError, "No api_key_env configured" unless env_var
+
+          key = ENV[env_var]
+          raise AuthError, "Environment variable '#{env_var}' is not set" unless key && !key.empty?
+
+          key
+        end
+
+        def timeout_seconds
+          @config['timeout_seconds'] || @config[:timeout_seconds] || 120
+        end
+      end
+
+      class ApiError < StandardError
+        attr_reader :provider, :retryable, :rate_limited, :suggested_backoff
+
+        def initialize(message, provider: nil, retryable: false, rate_limited: false, suggested_backoff: nil)
+          @provider = provider
+          @retryable = retryable
+          @rate_limited = rate_limited
+          @suggested_backoff = suggested_backoff
+          super(message)
+        end
+      end
+
+      class AuthError < ApiError
+        def initialize(message)
+          super(message, retryable: false)
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/llm_client/anthropic_adapter.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require_relative 'adapter'
+require_relative 'schema_converter'
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      class AnthropicAdapter < Adapter
+        API_URL = 'https://api.anthropic.com'
+        API_VERSION = '2023-06-01'
+
+        def call(messages:, system: nil, tools: nil, model: nil,
+                 max_tokens: nil, temperature: nil)
+          api_key = resolve_api_key
+
+          body = {
+            model: resolve_model(model),
+            max_tokens: resolve_max_tokens(max_tokens),
+            messages: convert_messages(messages)
+          }
+          body[:system] = system if system
+          body[:temperature] = resolve_temperature(temperature) unless temperature.nil?
+          body[:tools] = tools if tools && !tools.empty?
+
+          response = connection(api_key).post('/v1/messages') do |req|
+            req.body = JSON.generate(body)
+          end
+
+          parse_response(response)
+        rescue Faraday::TimeoutError => e
+          raise ApiError.new("Request timed out: #{e.message}",
+                             provider: 'anthropic', retryable: true)
+        rescue Faraday::ConnectionFailed => e
+          raise ApiError.new("Connection failed: #{e.message}",
+                             provider: 'anthropic', retryable: true)
+        rescue AuthError
+          raise
+        rescue StandardError => e
+          raise ApiError.new("Anthropic API error: #{e.message}", provider: 'anthropic')
+        end
+
+        private
+
+        def connection(api_key)
+          Faraday.new(url: API_URL) do |f|
+            f.request :json
+            f.headers['x-api-key'] = api_key
+            f.headers['anthropic-version'] = API_VERSION
+            f.headers['Content-Type'] = 'application/json'
+            f.options.timeout = timeout_seconds
+            f.options.open_timeout = 10
+            f.adapter Faraday.default_adapter
+          end
+        end
+
+        # Convert canonical intermediate messages to Anthropic API format.
+        # Canonical: role 'tool' + tool_use_id, assistant with tool_calls array.
+        # Anthropic: role 'user' + tool_result content block, assistant with tool_use content blocks.
+        # Messages already in Anthropic-native format pass through unchanged.
+        def convert_messages(messages)
+          messages.map do |msg|
+            role = msg['role'] || msg[:role]
+            content = msg['content'] || msg[:content]
+
+            case role
+            when 'tool'
+              tool_id = msg['tool_use_id'] || msg[:tool_use_id]
+              if tool_id
+                {
+                  'role' => 'user',
+                  'content' => [{ 'type' => 'tool_result',
+                                  'tool_use_id' => tool_id,
+                                  'content' => content.is_a?(String) ? content : JSON.generate(content) }]
+                }
+              else
+                msg  # Native format or unknown — pass through unchanged
+              end
+            when 'assistant'
+              tool_calls = msg['tool_calls'] || msg[:tool_calls]
+              if tool_calls && !tool_calls.empty?
+                content_blocks = []
+                content_blocks << { 'type' => 'text', 'text' => content } if content
+                tool_calls.each do |tc|
+                  content_blocks << {
+                    'type' => 'tool_use',
+                    'id' => tc['id'] || tc[:id],
+                    'name' => tc['name'] || tc[:name],
+                    'input' => tc['input'] || tc[:input] || {}
+                  }
+                end
+                { 'role' => 'assistant', 'content' => content_blocks }
+              else
+                { 'role' => role, 'content' => content }
+              end
+            else
+              { 'role' => role, 'content' => content }
+            end
+          end
+        end
+
+        def parse_response(response)
+          body = JSON.parse(response.body)
+
+          if response.status == 429
+            backoff = response.headers['retry-after']&.to_i
+            raise ApiError.new("Rate limited",
+                               provider: 'anthropic', retryable: true,
+                               rate_limited: true, suggested_backoff: backoff)
+          end
+
+          unless response.status == 200
+            raise ApiError.new(
+              body.dig('error', 'message') || "HTTP #{response.status}",
+              provider: 'anthropic',
+              retryable: response.status >= 500
+            )
+          end
+
+          normalize_response(body)
+        end
+
+        def normalize_response(body)
+          content_text = []
+          tool_use = []
+
+          (body['content'] || []).each do |block|
+            case block['type']
+            when 'text'
+              content_text << block['text']
+            when 'tool_use'
+              tool_use << {
+                'id' => block['id'],
+                'name' => block['name'],
+                'input' => block['input']
+              }
+            end
+          end
+
+          usage = body['usage'] || {}
+          {
+            'content' => content_text.empty? ? nil : content_text.join("\n"),
+            'tool_use' => tool_use.empty? ? nil : tool_use,
+            'stop_reason' => map_stop_reason(body['stop_reason']),
+            'model' => body['model'],
+            'input_tokens' => usage['input_tokens'],
+            'output_tokens' => usage['output_tokens']
+          }
+        end
+
+        def map_stop_reason(reason)
+          case reason
+          when 'end_turn' then 'end_turn'
+          when 'tool_use' then 'tool_use'
+          when 'max_tokens' then 'max_tokens'
+          when 'stop_sequence' then 'stop_sequence'
+          else reason || 'unknown'
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/llm_client/bedrock_adapter.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'adapter'
+require_relative 'schema_converter'
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      # Adapter for AWS Bedrock (Claude on AWS).
+      # Data stays within AWS — no external LLM provider data transfer.
+      # Requires: gem 'aws-sdk-bedrockruntime'
+      class BedrockAdapter < Adapter
+        def call(messages:, system: nil, tools: nil, model: nil,
+                 max_tokens: nil, temperature: nil)
+          client = bedrock_client
+
+          converted_messages = convert_messages(messages)
+
+          payload = {
+            anthropic_version: 'bedrock-2023-05-31',
+            max_tokens: resolve_max_tokens(max_tokens),
+            messages: converted_messages
+          }
+          payload[:system] = system if system
+          payload[:temperature] = resolve_temperature(temperature) unless temperature.nil?
+
+          if tools && !tools.empty?
+            payload[:tools] = tools.map do |t|
+              {
+                name: t[:name] || t['name'],
+                description: t[:description] || t['description'],
+                input_schema: t[:input_schema] || t['input_schema'] || t[:inputSchema] || t['inputSchema']
+              }
+            end
+          end
+
+          response = client.invoke_model(
+            model_id: resolve_model(model),
+            body: JSON.generate(payload),
+            content_type: 'application/json',
+            accept: 'application/json'
+          )
+
+          body = JSON.parse(response.body.string)
+          normalize_response(body)
+        rescue LoadError
+          raise ApiError.new(
+            "Bedrock adapter requires 'aws-sdk-bedrockruntime' gem. " \
+            "Add to Gemfile: gem 'aws-sdk-bedrockruntime', '~> 1.0'",
+            provider: 'bedrock', retryable: false
+          )
+        rescue AuthError
+          raise
+        rescue StandardError => e
+          if e.class.name.include?('Aws::')
+            retryable = e.respond_to?(:retryable?) ? e.retryable? : false
+            raise ApiError.new(
+              "Bedrock API error: #{e.message}",
+              provider: 'bedrock', retryable: retryable
+            )
+          end
+          raise ApiError.new("Bedrock error: #{e.message}", provider: 'bedrock')
+        end
+
+        private
+
+        def bedrock_client
+          begin
+            require 'aws-sdk-bedrockruntime'
+          rescue LoadError
+            raise LoadError, "aws-sdk-bedrockruntime not installed"
+          end
+
+          region = @config['aws_region'] || @config[:aws_region] ||
+                   ENV.fetch('AWS_REGION', 'us-east-1')
+
+          Aws::BedrockRuntime::Client.new(region: region)
+        end
+
+        def resolve_model(override)
+          override || @config['model'] || @config[:model] ||
+            ENV.fetch('AWS_BEDROCK_MODEL_ID', 'anthropic.claude-sonnet-4-5-20250929-v1:0')
+        end
+
+        def convert_messages(messages)
+          messages.map do |msg|
+            role = msg['role'] || msg[:role]
+            content = msg['content'] || msg[:content]
+
+            case role
+            when 'system'
+              # Bedrock system is a top-level parameter, not a message.
+              # If caller passes system in messages, convert to user context.
+              { role: 'user', content: "[System Context]: #{content}" }
+            when 'tool'
+              tool_id = msg['tool_use_id'] || msg[:tool_use_id]
+              {
+                role: 'user',
+                content: [{
+                  type: 'tool_result',
+                  tool_use_id: tool_id,
+                  content: content.is_a?(String) ? content : JSON.generate(content)
+                }]
+              }
+            when 'assistant'
+              tool_calls = msg['tool_calls'] || msg[:tool_calls]
+              if tool_calls
+                content_blocks = []
+                content_blocks << { type: 'text', text: content } if content
+                tool_calls.each do |tc|
+                  content_blocks << {
+                    type: 'tool_use',
+                    id: tc['id'] || tc[:id],
+                    name: tc['name'] || tc[:name],
+                    input: tc['input'] || tc[:input] || tc['arguments'] || tc[:arguments] || {}
+                  }
+                end
+                { role: 'assistant', content: content_blocks }
+              else
+                { role: 'assistant', content: content }
+              end
+            else
+              { role: role, content: content }
+            end
+          end
+        end
+
+        def normalize_response(body)
+          content_text = []
+          tool_use = []
+
+          (body['content'] || []).each do |block|
+            case block['type']
+            when 'text'
+              content_text << block['text']
+            when 'tool_use'
+              tool_use << {
+                'id' => block['id'],
+                'name' => block['name'],
+                'input' => block['input']
+              }
+            end
+          end
+
+          usage = body['usage'] || {}
+          {
+            'content' => content_text.empty? ? nil : content_text.join("\n"),
+            'tool_use' => tool_use.empty? ? nil : tool_use,
+            'stop_reason' => map_stop_reason(body['stop_reason']),
+            'model' => body['model'],
+            'input_tokens' => usage['input_tokens'],
+            'output_tokens' => usage['output_tokens']
+          }
+        end
+
+        def map_stop_reason(reason)
+          case reason
+          when 'end_turn' then 'end_turn'
+          when 'tool_use' then 'tool_use'
+          when 'max_tokens' then 'max_tokens'
+          when 'stop_sequence' then 'stop_sequence'
+          else reason || 'unknown'
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/llm_client/claude_code_adapter.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require_relative 'adapter'
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      # Adapter that uses Claude Code CLI as the LLM backend.
+      # No API costs — uses the Claude Code subscription.
+      # Invokes `claude -p --output-format json` as a subprocess.
+      class ClaudeCodeAdapter < Adapter
+        def call(messages:, system: nil, tools: nil, model: nil,
+                 max_tokens: nil, temperature: nil)
+          prompt = build_prompt(messages, system, tools)
+
+          args = ['claude', '-p', '--output-format', 'json']
+          args += ['--model', model] if model
+
+          stdout, stderr, status = Open3.capture3(*args, stdin_data: prompt)
+
+          unless status.success?
+            raise ApiError.new(
+              "Claude Code exited with status #{status.exitstatus}: #{stderr[0..200]}",
+              provider: 'claude_code', retryable: false
+            )
+          end
+
+          parse_response(stdout)
+        rescue Errno::ENOENT
+          raise ApiError.new(
+            "Claude Code CLI not found. Install: https://docs.anthropic.com/en/docs/claude-code",
+            provider: 'claude_code', retryable: false
+          )
+        rescue ApiError
+          raise
+        rescue StandardError => e
+          raise ApiError.new("Claude Code error: #{e.message}", provider: 'claude_code')
+        end
+
+        private
+
+        def build_prompt(messages, system, tools)
+          parts = []
+
+          if system
+            parts << "[System]: #{system}"
+            parts << ""
+          end
+
+          if tools && !tools.empty?
+            parts << "[Available tools - respond with JSON when you want to use a tool]:"
+            tools.each do |t|
+              name = t[:name] || t['name']
+              desc = t[:description] || t['description']
+              schema = t[:input_schema] || t['input_schema'] || t[:inputSchema] || t['inputSchema']
+              parts << "- #{name}: #{desc}"
+              if schema && schema.is_a?(Hash) && schema['properties']
+                params = schema['properties'].keys.join(', ')
+                parts << "  Parameters: #{params}"
+              end
+            end
+            parts << ""
+            parts << "To use a tool, include in your response:"
+            parts << '```json'
+            parts << '{"tool_use": [{"name": "tool_name", "input": {"param": "value"}}]}'
+            parts << '```'
+            parts << ""
+          end
+
+          messages.each do |msg|
+            role = msg['role'] || msg[:role]
+            content = msg['content'] || msg[:content]
+            case role
+            when 'user'
+              parts << content.to_s
+            when 'assistant'
+              parts << "[Previous assistant response]: #{content}"
+            when 'tool'
+              tool_id = msg['tool_use_id'] || msg[:tool_use_id] || 'unknown'
+              parts << "[Tool result for #{tool_id}]: #{content}"
+            end
+          end
+
+          parts.join("\n")
+        end
+
+        def parse_response(stdout)
+          data = JSON.parse(stdout)
+
+          unless data['type'] == 'result'
+            raise ApiError.new(
+              "Unexpected Claude Code response type: #{data['type']}",
+              provider: 'claude_code'
+            )
+          end
+
+          if data['is_error']
+            raise ApiError.new(
+              data['result'] || 'Claude Code returned an error',
+              provider: 'claude_code', retryable: false
+            )
+          end
+
+          result_text = data['result'] || ''
+          tool_use = extract_tool_use(result_text)
+          usage = data['usage'] || {}
+
+          {
+            'content' => tool_use ? nil : result_text,
+            'tool_use' => tool_use,
+            'stop_reason' => tool_use ? 'tool_use' : map_stop_reason(data['stop_reason']),
+            'model' => data.dig('modelUsage')&.keys&.first || 'claude_code',
+            'input_tokens' => usage['input_tokens'],
+            'output_tokens' => usage['output_tokens']
+          }
+        end
+
+        # Try to extract tool_use JSON from Claude Code's text response
+        def extract_tool_use(text)
+          # Look for JSON block with tool_use
+          json_match = text.match(/```json\s*\n?(.*?)\n?\s*```/m) ||
+                       text.match(/\{[^{}]*"tool_use"\s*:/m)
+
+          return nil unless json_match
+
+          json_str = json_match[1] || json_match[0]
+          parsed = JSON.parse(json_str)
+
+          if parsed.is_a?(Hash) && parsed['tool_use'].is_a?(Array)
+            parsed['tool_use'].map do |tu|
+              {
+                'id' => "cc_#{SecureRandom.hex(4)}",
+                'name' => tu['name'],
+                'input' => tu['input'] || {}
+              }
+            end
+          end
+        rescue JSON::ParserError
+          nil
+        end
+
+        def map_stop_reason(reason)
+          case reason
+          when 'end_turn' then 'end_turn'
+          when 'max_tokens' then 'max_tokens'
+          else reason || 'end_turn'
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/llm_client/openai_adapter.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require_relative 'adapter'
+require_relative 'schema_converter'
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      class OpenaiAdapter < Adapter
+        API_URL = 'https://api.openai.com'
+
+        def call(messages:, system: nil, tools: nil, model: nil,
+                 max_tokens: nil, temperature: nil)
+          api_key = resolve_api_key
+
+          all_messages = []
+          all_messages << { 'role' => 'system', 'content' => system } if system
+          all_messages.concat(messages)
+          all_messages = convert_messages(all_messages)
+
+          body = {
+            model: resolve_model(model),
+            max_tokens: resolve_max_tokens(max_tokens),
+            messages: all_messages,
+            temperature: resolve_temperature(temperature)
+          }
+          body[:tools] = tools if tools && !tools.empty?
+
+          response = connection(api_key).post('/v1/chat/completions') do |req|
+            req.body = JSON.generate(body)
+          end
+
+          parse_response(response)
+        rescue Faraday::TimeoutError => e
+          raise ApiError.new("Request timed out: #{e.message}",
+                             provider: 'openai', retryable: true)
+        rescue Faraday::ConnectionFailed => e
+          raise ApiError.new("Connection failed: #{e.message}",
+                             provider: 'openai', retryable: true)
+        rescue AuthError
+          raise
+        rescue StandardError => e
+          raise ApiError.new("OpenAI API error: #{e.message}", provider: 'openai')
+        end
+
+        private
+
+        def connection(api_key)
+          Faraday.new(url: base_url) do |f|
+            f.request :json
+            f.headers['Authorization'] = "Bearer #{api_key}"
+            f.headers['Content-Type'] = 'application/json'
+            f.options.timeout = timeout_seconds
+            f.options.open_timeout = 10
+            f.adapter Faraday.default_adapter
+          end
+        end
+
+        def base_url
+          @config['base_url'] || @config[:base_url] || API_URL
+        end
+
+        # Convert canonical intermediate messages to OpenAI API format.
+        # Canonical: role 'tool' + tool_use_id, assistant with tool_calls [{id, name, input}].
+        # OpenAI: role 'tool' + tool_call_id, assistant with tool_calls [{id, type, function}].
+        # Messages already in OpenAI-native format pass through unchanged.
+        def convert_messages(messages)
+          messages.map do |msg|
+            role = msg['role'] || msg[:role]
+            content = msg['content'] || msg[:content]
+
+            case role
+            when 'tool'
+              tool_call_id = msg['tool_call_id'] || msg[:tool_call_id] ||
+                             msg['tool_use_id'] || msg[:tool_use_id]
+              if tool_call_id
+                { 'role' => 'tool',
+                  'tool_call_id' => tool_call_id,
+                  'content' => content.is_a?(String) ? content : JSON.generate(content) }
+              else
+                msg  # Native format or unknown — pass through unchanged
+              end
+            when 'assistant'
+              tool_calls = msg['tool_calls'] || msg[:tool_calls]
+              if tool_calls && tool_calls.first && !tool_calls.first.key?('type')
+                { 'role' => 'assistant',
+                  'content' => content,
+                  'tool_calls' => tool_calls.map { |tc|
+                    { 'id' => tc['id'] || tc[:id],
+                      'type' => 'function',
+                      'function' => {
+                        'name' => tc['name'] || tc[:name],
+                        'arguments' => JSON.generate(tc['input'] || tc[:input] || {})
+                      } }
+                  } }
+              else
+                msg
+              end
+            else
+              msg
+            end
+          end
+        end
+
+        def parse_response(response)
+          body = JSON.parse(response.body)
+
+          if response.status == 429
+            backoff = response.headers['retry-after']&.to_i
+            raise ApiError.new("Rate limited",
+                               provider: 'openai', retryable: true,
+                               rate_limited: true, suggested_backoff: backoff)
+          end
+
+          unless response.status == 200
+            raise ApiError.new(
+              body.dig('error', 'message') || "HTTP #{response.status}",
+              provider: 'openai',
+              retryable: response.status >= 500
+            )
+          end
+
+          normalize_response(body)
+        end
+
+        def normalize_response(body)
+          choice = body.dig('choices', 0, 'message') || {}
+
+          tool_use = nil
+          if choice['tool_calls']
+            tool_use = choice['tool_calls'].map do |tc|
+              input = begin
+                JSON.parse(tc.dig('function', 'arguments') || '{}')
+              rescue JSON::ParserError
+                { '_raw' => tc.dig('function', 'arguments') }
+              end
+              {
+                'id' => tc['id'],
+                'name' => tc.dig('function', 'name'),
+                'input' => input
+              }
+            end
+          end
+
+          usage = body['usage'] || {}
+          {
+            'content' => choice['content'],
+            'tool_use' => tool_use,
+            'stop_reason' => map_stop_reason(choice['finish_reason'] || body.dig('choices', 0, 'finish_reason')),
+            'model' => body['model'],
+            'input_tokens' => usage['prompt_tokens'],
+            'output_tokens' => usage['completion_tokens']
+          }
+        end
+
+        # OpenAI finish_reason → canonical stop_reason
+        def map_stop_reason(reason)
+          case reason
+          when 'stop' then 'end_turn'
+          when 'tool_calls' then 'tool_use'
+          when 'length' then 'max_tokens'
+          when 'content_filter' then 'content_filter'
+          else reason || 'unknown'
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/llm_client/schema_converter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      # Converts MCP tool schemas to LLM provider formats.
+      module SchemaConverter
+        module_function
+
+        # MCP → Anthropic: rename inputSchema → input_schema
+        def to_anthropic(mcp_schema)
+          {
+            name: mcp_schema[:name],
+            description: truncate_description(mcp_schema[:description], 4096),
+            input_schema: mcp_schema[:inputSchema] || { type: 'object', properties: {} }
+          }
+        end
+
+        # MCP → OpenAI: wrap in function envelope, normalize JSON Schema
+        def to_openai(mcp_schema)
+          params = normalize_for_openai(mcp_schema[:inputSchema] || { type: 'object', properties: {} })
+          {
+            type: 'function',
+            function: {
+              name: mcp_schema[:name],
+              description: truncate_description(mcp_schema[:description], 1024),
+              parameters: params
+            }
+          }
+        end
+
+        # Batch convert with error isolation per tool
+        def convert_batch(mcp_schemas, target)
+          converter = target == :openai ? method(:to_openai) : method(:to_anthropic)
+          results = []
+          errors = []
+
+          mcp_schemas.each do |schema|
+            results << converter.call(schema)
+          rescue StandardError => e
+            errors << { tool: schema[:name], error: e.message }
+          end
+
+          { schemas: results, errors: errors }
+        end
+
+        # Normalize JSON Schema for OpenAI strict mode compatibility
+        def normalize_for_openai(schema)
+          return schema unless schema.is_a?(Hash)
+
+          normalized = schema.dup
+
+          if normalized['type'] == 'object' || normalized[:type] == 'object'
+            # OpenAI requires explicit additionalProperties: false
+            key = normalized.key?(:type) ? :additionalProperties : 'additionalProperties'
+            normalized[key] = false unless normalized.key?(key) || normalized.key?(:additionalProperties) || normalized.key?('additionalProperties')
+          end
+
+          # Recursively normalize nested properties
+          props_key = normalized.key?(:properties) ? :properties : 'properties'
+          if normalized[props_key].is_a?(Hash)
+            normalized[props_key] = normalized[props_key].transform_values { |v| normalize_for_openai(v) }
+          end
+
+          # Normalize items in arrays
+          items_key = normalized.key?(:items) ? :items : 'items'
+          if normalized[items_key].is_a?(Hash)
+            normalized[items_key] = normalize_for_openai(normalized[items_key])
+          end
+
+          normalized
+        end
+
+        def truncate_description(desc, max_len)
+          return '' if desc.nil?
+          desc.length > max_len ? "#{desc[0...max_len - 3]}..." : desc
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/llm_client.yml

@@ -0,0 +1,48 @@
+# LLM Client Configuration
+# API keys are NEVER stored here — only env var names.
+#
+# Supported providers:
+#   anthropic    — Direct Anthropic API (requires ANTHROPIC_API_KEY)
+#   openai       — Direct OpenAI API (requires OPENAI_API_KEY)
+#   openrouter   — OpenRouter proxy (requires OPENROUTER_API_KEY, set base_url)
+#   bedrock      — AWS Bedrock (uses AWS credentials, data stays in AWS)
+#   claude_code  — Claude Code CLI subprocess (subscription, no API cost)
+#   local        — Local model via OpenAI-compatible API (Ollama, vLLM)
+
+provider: anthropic
+model: claude-sonnet-4-6
+api_key_env: ANTHROPIC_API_KEY
+default_max_tokens: 4096
+default_temperature: 0.7
+timeout_seconds: 120
+
+# --- Provider-specific examples (uncomment one) ---
+
+# # OpenRouter (cheaper API proxy, supports many models):
+# provider: openrouter
+# model: anthropic/claude-sonnet-4-6
+# api_key_env: OPENROUTER_API_KEY
+# base_url: https://openrouter.ai/api/v1
+
+# # AWS Bedrock (data stays within AWS):
+# provider: bedrock
+# model: anthropic.claude-sonnet-4-5-20250929-v1:0
+# aws_region: us-east-1
+# # Uses AWS credentials from environment (AWS_ACCESS_KEY_ID, etc. or IAM role)
+
+# # Claude Code CLI (subscription, no API cost):
+# provider: claude_code
+# # No api_key_env needed — uses Claude Code subscription auth
+
+# # Local model (Ollama):
+# provider: local
+# model: llama3.2
+# base_url: http://127.0.0.1:11434/v1
+
+# Cost estimates (USD per 1M tokens, for llm_status display)
+cost_estimates:
+  claude-sonnet-4-6: { input: 3.0, output: 15.0 }
+  claude-haiku-4-5: { input: 0.80, output: 4.0 }
+  claude-opus-4-6: { input: 15.0, output: 75.0 }
+  gpt-4o: { input: 2.50, output: 10.0 }
+  gpt-4o-mini: { input: 0.15, output: 0.60 }

data/templates/skillsets/llm_client/llm_configure.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      module Tools
+        class LlmConfigure < KairosMcp::Tools::BaseTool
+          def name
+            'llm_configure'
+          end
+
+          def description
+            'Set or change the LLM provider, model, and API key env var. ' \
+              'API keys are never stored — only the environment variable name.'
+          end
+
+          def category
+            :llm
+          end
+
+          def input_schema
+            {
+              type: 'object',
+              properties: {
+                provider: {
+                  type: 'string',
+                  description: 'Provider: "anthropic", "openai", or "local"',
+                  enum: %w[anthropic openai local]
+                },
+                model: { type: 'string', description: 'Model name' },
+                api_key_env: { type: 'string', description: 'Environment variable name for API key' },
+                base_url: { type: 'string', description: 'Base URL override (for local/proxy)' },
+                default_max_tokens: { type: 'integer' },
+                default_temperature: { type: 'number' }
+              }
+            }
+          end
+
+          def call(arguments)
+            config_path = File.join(__dir__, '..', 'config', 'llm_client.yml')
+            config = if File.exist?(config_path)
+                       YAML.safe_load(File.read(config_path), permitted_classes: [Symbol]) || {}
+                     else
+                       {}
+                     end
+
+            # Update only provided fields
+            %w[provider model api_key_env base_url default_max_tokens default_temperature].each do |key|
+              config[key] = arguments[key] if arguments.key?(key)
+            end
+
+            # Remove base_url if nil (reset to default)
+            config.delete('base_url') if config['base_url'].nil?
+
+            File.write(config_path, YAML.dump(config))
+
+            text_content(JSON.generate({
+              'status' => 'ok',
+              'message' => "Configuration updated",
+              'config' => config.reject { |k, _| k == 'cost_estimates' }
+            }))
+          rescue StandardError => e
+            text_content(JSON.generate({
+              'status' => 'error',
+              'error' => { 'type' => 'config_error', 'message' => e.message }
+            }))
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/llm_status.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+module KairosMcp
+  module SkillSets
+    module LlmClient
+      module Tools
+        class LlmStatus < KairosMcp::Tools::BaseTool
+          def name
+            'llm_status'
+          end
+
+          def description
+            'Show current LLM provider configuration and session usage statistics.'
+          end
+
+          def category
+            :llm
+          end
+
+          def input_schema
+            { type: 'object', properties: {} }
+          end
+
+          def call(arguments)
+            config_path = File.join(__dir__, '..', 'config', 'llm_client.yml')
+            config = if File.exist?(config_path)
+                       YAML.safe_load(File.read(config_path), permitted_classes: [Symbol]) || {}
+                     else
+                       {}
+                     end
+
+            api_key_env = config['api_key_env']
+            api_key_set = api_key_env && ENV[api_key_env] && !ENV[api_key_env].empty?
+
+            stats = UsageTracker.stats
+            cost_estimates = config['cost_estimates'] || {}
+            model = config['model'] || 'unknown'
+            model_cost = cost_estimates[model] || {}
+
+            estimated_cost = 0.0
+            if model_cost.any?
+              input_cost = (model_cost['input'] || model_cost[:input] || 0).to_f
+              output_cost = (model_cost['output'] || model_cost[:output] || 0).to_f
+              estimated_cost = (stats[:input_tokens] * input_cost + stats[:output_tokens] * output_cost) / 1_000_000.0
+            end
+
+            text_content(JSON.generate({
+              'provider' => config['provider'] || 'not configured',
+              'model' => model,
+              'api_key_configured' => api_key_set || false,
+              'session_usage' => {
+                'total_calls' => stats[:calls],
+                'total_input_tokens' => stats[:input_tokens],
+                'total_output_tokens' => stats[:output_tokens],
+                'total_cost_estimate_usd' => estimated_cost.round(4)
+              }
+            }))
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/llm_client/skillset.json

@@ -0,0 +1,22 @@
+{
+  "name": "llm_client",
+  "version": "0.1.0",
+  "description": "Pure LLM provider abstraction. One API call, returns response. No loop, no retry, no fallback.",
+  "author": "Masaomi Hatakeyama",
+  "layer": "L1",
+  "depends_on": [],
+  "provides": [
+    "llm_api_call",
+    "llm_configuration",
+    "schema_conversion"
+  ],
+  "tool_classes": [
+    "KairosMcp::SkillSets::LlmClient::Tools::LlmCall",
+    "KairosMcp::SkillSets::LlmClient::Tools::LlmConfigure",
+    "KairosMcp::SkillSets::LlmClient::Tools::LlmStatus"
+  ],
+  "config_files": ["config/llm_client.yml"],
+  "knowledge_dirs": ["knowledge/llm_client_guide"],
+  "gem_dependencies": ["faraday"],
+  "min_core_version": "2.8.0"
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.9.1
 platform: ruby
 authors:
 - Masaomi Hatakeyama
@@ -307,6 +307,17 @@ files:
 - templates/skillsets/knowledge_creator/skillset.json
 - templates/skillsets/knowledge_creator/tools/kc_compare.rb
 - templates/skillsets/knowledge_creator/tools/kc_evaluate.rb
+- templates/skillsets/llm_client/llm_call.rb
+- templates/skillsets/llm_client/llm_client.yml
+- templates/skillsets/llm_client/llm_client/adapter.rb
+- templates/skillsets/llm_client/llm_client/anthropic_adapter.rb
+- templates/skillsets/llm_client/llm_client/bedrock_adapter.rb
+- templates/skillsets/llm_client/llm_client/claude_code_adapter.rb
+- templates/skillsets/llm_client/llm_client/openai_adapter.rb
+- templates/skillsets/llm_client/llm_client/schema_converter.rb
+- templates/skillsets/llm_client/llm_configure.rb
+- templates/skillsets/llm_client/llm_status.rb
+- templates/skillsets/llm_client/skillset.json
 - templates/skillsets/mcp_client/config/mcp_client.yml
 - templates/skillsets/mcp_client/lib/mcp_client.rb
 - templates/skillsets/mcp_client/lib/mcp_client/client.rb