kairos-chain 3.11.0 → 3.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0acca30b533051c884363e6c9215394d308f501985a6dc647f92c513e875ce6b
-  data.tar.gz: 862c366ebcb1f88a66eb5c30b48086e454145609d57f1fbb8ba6aa62aeb89652
+  metadata.gz: 9e4f14b45f5ece26ac4279095f818d8772efcf5ae0d1dfb95924e2f69a2c2bcc
+  data.tar.gz: a51ac4d001f7e5c5c17491fdb168da11b04d17502972d80d1119ac99f2243acf
 SHA512:
-  metadata.gz: 9066154fcf88d0e39457fca4c4f4ebac74e7104c9d5d2bf047783e2f058ddfc9b03e38be965f492ac914b81eb611da50cff7e63264e6a16caadf0e23d8d707ef
-  data.tar.gz: b7324da5f140698a74d11e94dedee3a3bdc2d778a9f0f2ca12417861bb5a5b23ad96eb6f4ad94077c1b6f72cbc2f2e0c3651c62d08242452451d7f0ada75d330
+  metadata.gz: 0cb3cba2544bbb1244945199b783db04da81573dfde6d45d8c1c46d0c310e0fe26e9c521b7983263e66ec2d363c5614f630336ecdd10af056ca3ea9cb8b5ccf6
+  data.tar.gz: 64ef0f93ebc9922c5acc8bbc6f0733734e9be5445c810f51f1c2b4f55c975764f39277bf07d48a5d1477010fdb7b1c7dfe9452f88bcf3db0ed8bbd1339caf3f9

data/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.12.0] - 2026-04-02
+
+### Added
+
+- **`skillset_exchange` SkillSet** (v0.1.0) — New L1 SkillSet enabling knowledge-only
+  SkillSet deposit, browse, acquire, and withdraw via HestiaChain Meeting Places.
+  - **PlaceRouter extension mechanism** — Formal extension registry with `register_extension`,
+    `route_action_map`, dispatch after auth/middleware. Enables SkillSets to add HTTP
+    endpoints to HestiaChain PlaceRouter without modifying Hestia core.
+  - **4 MCP tools**: `skillset_deposit`, `skillset_browse`, `skillset_acquire`, `skillset_withdraw`
+  - **PlaceExtension**: 4 HTTP endpoints (`/place/v1/skillset_deposit`, `skillset_browse`,
+    `skillset_content`, `skillset_withdraw`) with disk-backed storage and quotas
+  - **Security**: Dual executable gate (server tar header scan + client `knowledge_only?`),
+    content hash verification (file-tree hash), signature verification with `require_signature`
+    enforcement, path traversal protection, Content-Length pre-check, metadata canonicalization
+    from verified archive contents
+  - **DEE compliance**: Random sampling for browse, no ranking or popularity metrics
+  - **ExchangeValidator**: Single gatekeeper for deposit eligibility
+  - Lazy extension registration for late SkillSet enablement
+  - Configurable quotas: 5MB/archive, 10/agent, 100MB total (default)
+- **`SkillSetManager#install_from_archive` `force:` parameter** — Atomic swap reinstall
+  with config preservation for SkillSet upgrades via exchange.
+- **`SkillSetManager#check_installable_dependencies`** — Public preflight method returning
+  structured result (`satisfiable`, `missing`, `version_mismatch`, `disabled`) without raising.
+- **`Skillset#place_extensions`** — Metadata accessor for PlaceRouter extension declarations.
+
+### Design Process
+
+- Design: 2 rounds x 3 LLMs → APPROVED (0 FAIL)
+- Phase 1 impl: 1R x 3 LLMs → fixes applied
+- Phase 2 impl: 2R x 3 LLMs → fixes applied (Codex REJECT resolved)
+- Phase 3 design: 2R x 3 LLMs → APPROVED
+- Phase 3 impl: 1R x 3 LLMs → fixes applied
+- Final comprehensive: 1R x 3 LLMs → fixes applied (SecurityError, metadata canonicalization)
+- Tests: 303 total (Phase 1: 44, Phase 2: 85, Phase 3: 80, Phase 4: 94)
+
 ## [3.11.0] - 2026-04-01
 
 ### Added

data/lib/kairos_mcp/http_server.rb

@@ -283,6 +283,9 @@ module KairosMcp
         trust_anchor_client: trust_anchor_client
       )
       @place_router = router
+
+      # Register place extensions from enabled SkillSets
+      register_place_extensions(router)
     end
 
     # -----------------------------------------------------------------------
@@ -295,6 +298,30 @@ module KairosMcp
 
     private
 
+    # Register place extensions from enabled SkillSets that declare place_extensions.
+    # Uses KairosMcp.http_server pattern for late registration access.
+    def register_place_extensions(router)
+      require_relative 'skillset_manager'
+      SkillSetManager.new.enabled_skillsets.each do |ss|
+        next unless ss.place_extensions.any?
+
+        ss.place_extensions.each do |ext_def|
+          require_path = File.join(ss.path, ext_def['require'])
+          require require_path
+          ext_class = Object.const_get(ext_def['class'])
+          router.register_extension(
+            ext_class.new(router),
+            route_action_map: ext_def['route_actions'] || {}
+          )
+        rescue StandardError => e
+          $stderr.puts "[HttpServer] Failed to load extension '#{ext_def['class']}' " \
+                       "from SkillSet '#{ss.name}': #{e.message}"
+        end
+      end
+    rescue StandardError => e
+      $stderr.puts "[HttpServer] Extension registration failed (non-fatal): #{e.message}"
+    end
+
     # Auto-start Meeting Place if hestia.yml has meeting_place.enabled: true
     def auto_start_meeting_place
       require 'hestia'

data/lib/kairos_mcp/skillset.rb

@@ -78,6 +78,12 @@ module KairosMcp
       @metadata['knowledge_dirs'] || []
     end
 
+    # Place extension declarations for PlaceRouter integration.
+    # Returns Array of Hashes, each with 'class', 'require', 'route_actions'.
+    def place_extensions
+      @metadata['place_extensions'] || []
+    end
+
     def index_knowledge?
       return @metadata['index_knowledge'] == true if @metadata.key?('index_knowledge')
 

data/lib/kairos_mcp/skillset_manager.rb

@@ -294,8 +294,9 @@ module KairosMcp
       }
     end
 
-    # Install a SkillSet from a Base64-encoded tar.gz archive
-    def install_from_archive(archive_data, layer_override: nil)
+    # Install a SkillSet from a Base64-encoded tar.gz archive.
+    # With force: true, replaces an existing SkillSet (preserves config/ files).
+    def install_from_archive(archive_data, layer_override: nil, force: false)
       archive_data = symbolize_keys(archive_data)
       name = archive_data[:name]
       raise ArgumentError, "Archive missing 'name'" unless name
@@ -303,7 +304,9 @@ module KairosMcp
       raise ArgumentError, "Archive missing 'archive_base64'" unless archive_data[:archive_base64]
 
       dest = File.join(@skillsets_dir, name)
-      raise ArgumentError, "SkillSet '#{name}' already installed at #{dest}" if File.directory?(dest)
+      if File.directory?(dest) && !force
+        raise ArgumentError, "SkillSet '#{name}' already installed at #{dest}. Use force: true to reinstall."
+      end
 
       Dir.mktmpdir('kairos_ss_install') do |tmpdir|
         tar_gz_data = Base64.strict_decode64(archive_data[:archive_base64])
@@ -330,21 +333,89 @@ module KairosMcp
           end
         end
 
-        FileUtils.mkdir_p(@skillsets_dir)
-        FileUtils.cp_r(extracted, dest)
+        # Force reinstall: stage in temp dir (already done above), then atomic swap
+        if File.directory?(dest) && force
+          # Preserve user config files
+          config_dir = File.join(dest, 'config')
+          saved_configs = {}
+          if File.directory?(config_dir)
+            Dir.glob(File.join(config_dir, '*')).each do |f|
+              saved_configs[File.basename(f)] = File.read(f) if File.file?(f)
+            end
+          end
+
+          # Atomic swap: remove old, move new into place
+          FileUtils.rm_rf(dest)
+          FileUtils.cp_r(extracted, dest)
+
+          # Restore preserved config
+          unless saved_configs.empty?
+            FileUtils.mkdir_p(File.join(dest, 'config'))
+            saved_configs.each do |fname, content|
+              File.write(File.join(dest, 'config', fname), content)
+            end
+          end
+        else
+          FileUtils.mkdir_p(@skillsets_dir)
+          FileUtils.cp_r(extracted, dest)
+        end
 
         installed = Skillset.new(dest)
         installed.layer = layer_override if layer_override
 
         set_config(installed.name, 'layer_override', layer_override.to_s) if layer_override
         set_config(installed.name, 'enabled', true)
-        record_skillset_event(installed, 'install_from_archive')
+        record_skillset_event(installed, force ? 'reinstall_from_archive' : 'install_from_archive')
 
         { success: true, name: installed.name, version: installed.version,
           layer: installed.layer, path: dest, content_hash: installed.content_hash }
       end
     end
 
+    # Check if a SkillSet's dependencies can be satisfied locally.
+    # Returns a structured result (does NOT raise).
+    #
+    # @param skillset [Skillset] A Skillset object (from archive or installed)
+    # @return [Hash] { satisfiable:, missing:, version_mismatch:, disabled: }
+    def check_installable_dependencies(skillset)
+      result = { satisfiable: true, missing: [], version_mismatch: [], disabled: [] }
+      skillset.depends_on_with_versions.each do |dep|
+        installed = find_skillset(dep[:name])
+        if installed.nil?
+          result[:satisfiable] = false
+          result[:missing] << dep[:name]
+          next
+        end
+
+        unless enabled?(dep[:name])
+          result[:disabled] << dep[:name]
+        end
+
+        next unless dep[:version]
+
+        begin
+          requirement = Gem::Requirement.new(*dep[:version].split(',').map(&:strip))
+          unless requirement.satisfied_by?(Gem::Version.new(installed.version))
+            result[:satisfiable] = false
+            result[:version_mismatch] << {
+              name: dep[:name],
+              required: dep[:version],
+              installed: installed.version
+            }
+          end
+        rescue Gem::Requirement::BadRequirementError
+          result[:satisfiable] = false
+          result[:version_mismatch] << {
+            name: dep[:name],
+            required: dep[:version],
+            installed: installed.version,
+            error: 'invalid version constraint'
+          }
+        end
+      end
+      result
+    end
+
     # Get info about a specific SkillSet
     def info(name)
       skillset = find_skillset(name)

data/lib/kairos_mcp/version.rb

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

data/templates/skillsets/hestia/lib/hestia/place_router.rb

@@ -55,7 +55,7 @@ module Hestia
       end
     end
 
-    attr_reader :registry, :skill_board, :heartbeat_manager, :session_store, :started_at
+    attr_reader :registry, :skill_board, :heartbeat_manager, :session_store, :started_at, :extensions
 
     def initialize(config: nil)
       @config = config || ::Hestia.load_config
@@ -66,6 +66,21 @@ module Hestia
       @started = false
       @started_at = nil
       @self_id = nil
+      @extensions = []
+      @extension_action_map = {}
+    end
+
+    # Register a PlaceRouter extension for additional endpoint handling.
+    # Extensions receive authenticated requests and return Rack responses or nil.
+    # Idempotent: skips if an extension of the same class is already registered.
+    #
+    # @param extension [Object] Extension instance responding to #call(env, peer_id:)
+    # @param route_action_map [Hash] Maps route segments to action names for access control
+    def register_extension(extension, route_action_map: {})
+      return if @extensions.any? { |e| e.class == extension.class }
+
+      @extensions << extension
+      @extension_action_map.merge!(route_action_map)
     end
 
     # Start the Meeting Place: initialize components and self-register.
@@ -203,6 +218,10 @@ module Hestia
         elsif request_method == 'GET' && path.start_with?('/place/v1/agent_profile/')
           handle_agent_profile(path)
         else
+          # Extension dispatch: check registered extensions before 404
+          ext_result = dispatch_extensions(env, peer_id: peer_id)
+          return ext_result if ext_result
+
           json_response(404, { error: 'not_found', message: "Unknown place endpoint: #{path}" })
         end
       end
@@ -859,8 +878,9 @@ module Hestia
     end
 
     # Map route segment to abstract action name for access control.
+    # Checks built-in ROUTE_ACTION_MAP first, then extension action map.
     def resolve_action(route_segment)
-      ROUTE_ACTION_MAP[route_segment] || route_segment
+      ROUTE_ACTION_MAP[route_segment] || @extension_action_map[route_segment] || route_segment
     end
 
     # Run registered place middlewares. Returns nil if all pass,
@@ -876,6 +896,16 @@ module Hestia
       nil
     end
 
+    # Dispatch request to registered extensions.
+    # Returns Rack response if an extension handles it, nil otherwise.
+    def dispatch_extensions(env, peer_id:)
+      @extensions.each do |ext|
+        result = ext.call(env, peer_id: peer_id)
+        return result if result
+      end
+      nil
+    end
+
     # Service name for this Meeting Place instance
     def service_name
       @config.dig('meeting_place', 'service_name') || 'meeting_place'

data/templates/skillsets/hestia/tools/meeting_place_start.rb

@@ -90,6 +90,9 @@ module KairosMcp
               trust_scorer: scorer
             )
 
+            # Register place extensions from enabled SkillSets
+            register_extensions(place_router)
+
             text_content(JSON.pretty_generate(result))
           rescue StandardError => e
             text_content(JSON.pretty_generate({
@@ -100,6 +103,31 @@ module KairosMcp
 
           private
 
+          # Register place extensions from enabled SkillSets that declare place_extensions.
+          # Iterates all enabled SkillSets, requires extension files, and registers with the router.
+          # Errors are logged but do not block Place startup.
+          def register_extensions(router)
+            manager = ::KairosMcp::SkillSetManager.new
+            manager.enabled_skillsets.each do |ss|
+              next unless ss.place_extensions.any?
+
+              ss.place_extensions.each do |ext_def|
+                require_path = File.join(ss.path, ext_def['require'])
+                require require_path
+                ext_class = Object.const_get(ext_def['class'])
+                router.register_extension(
+                  ext_class.new(router),
+                  route_action_map: ext_def['route_actions'] || {}
+                )
+              rescue StandardError => e
+                $stderr.puts "[MeetingPlaceStart] Failed to load extension '#{ext_def['class']}' " \
+                             "from SkillSet '#{ss.name}': #{e.message}"
+              end
+            end
+          rescue StandardError => e
+            $stderr.puts "[MeetingPlaceStart] Extension registration failed (non-fatal): #{e.message}"
+          end
+
           # Runtime detection of Synoptis SkillSet.
           # Returns a TrustScorer instance if Synoptis is loaded, nil otherwise.
           # This follows the core_or_skillset_guide pattern for optional dependencies.

data/templates/skillsets/skillset_exchange/config/skillset_exchange.yml

@@ -0,0 +1,15 @@
+# SkillSet Exchange configuration
+enabled: true
+
+deposit:
+  max_archive_size_bytes: 5242880      # 5MB per archive
+  max_per_agent: 10                     # max SkillSet deposits per agent
+  require_signature: true               # Require depositor signature
+
+acquire:
+  verify_signature: true                # Verify depositor signature on acquire
+  check_dependencies: true              # Warn about missing dependencies
+
+place:
+  max_total_archive_bytes: 104857600   # 100MB total across all agents
+  storage_dir: skillset_deposits        # relative to hestia storage path

data/templates/skillsets/skillset_exchange/knowledge/skillset_exchange_guide/skillset_exchange_guide.md

@@ -0,0 +1,48 @@
+---
+name: skillset_exchange_guide
+description: Guide for depositing, browsing, and acquiring SkillSets via Meeting Place
+version: 0.1.0
+tags:
+  - skillset
+  - exchange
+  - meeting_place
+  - guide
+type: reference
+public: true
+---
+
+# SkillSet Exchange Guide
+
+## Overview
+
+The SkillSet Exchange enables agents to deposit, browse, and acquire bundled knowledge
+packages (SkillSets) through a Meeting Place. Only knowledge-only SkillSets (no executable
+code) are exchangeable.
+
+## Workflow
+
+1. **Connect** to a Meeting Place: `meeting_connect(url: "...")`
+2. **Deposit** a knowledge SkillSet: `skillset_deposit(name: "my_knowledge_pack")`
+3. **Browse** available SkillSets: `skillset_browse(search: "genomics")`
+4. **Acquire** a SkillSet: `skillset_acquire(name: "...", depositor_id: "...")`
+5. **Withdraw** a deposit: `skillset_withdraw(name: "...", reason: "...")`
+
+## Security Model
+
+- Only knowledge-only SkillSets can be deposited (no `.rb`, `.py`, `.sh`, etc.)
+- Archives are scanned for executable content at deposit time (tar header scan)
+- Content hashes are verified on both deposit and acquire
+- Deposits are signed by the depositor's cryptographic key
+- The acquirer's `install_from_archive` independently verifies `knowledge_only?`
+
+## DEE Compliance
+
+Browse results are returned in random order. No ranking, scoring, or popularity
+metrics are exposed. Each agent decides locally whether a SkillSet is useful.
+
+## Configuration
+
+Edit `config/skillset_exchange.yml` to adjust:
+- `deposit.max_archive_size_bytes`: Maximum archive size (default 5MB)
+- `deposit.max_per_agent`: Maximum deposits per agent (default 10)
+- `place.max_total_archive_bytes`: Total storage quota (default 100MB)

data/templates/skillsets/skillset_exchange/lib/skillset_exchange/exchange_validator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module SkillsetExchange
+  # Single gatekeeper for SkillSet deposit eligibility.
+  #
+  # Validates that a SkillSet is safe to deposit:
+  # - Name matches safe pattern
+  # - SkillSet exists and is exchangeable (knowledge_only? + valid?)
+  # - Estimated archive size within limit
+  class ExchangeValidator
+    SAFE_NAME_PATTERN = /\A[a-zA-Z0-9][a-zA-Z0-9_-]*\z/
+
+    def initialize(config: {})
+      @max_archive_size = config.dig('deposit', 'max_archive_size_bytes') || 5_242_880
+    end
+
+    # Validate a SkillSet for deposit eligibility.
+    #
+    # @param name [String] SkillSet name
+    # @param manager [KairosMcp::SkillSetManager, nil] Manager instance (auto-created if nil)
+    # @return [Hash] { valid: Boolean, errors: Array<String> }
+    def validate_for_deposit(name, manager: nil)
+      manager ||= ::KairosMcp::SkillSetManager.new
+      errors = []
+
+      # Name validation
+      errors << "Invalid SkillSet name" unless SAFE_NAME_PATTERN.match?(name.to_s)
+
+      ss = manager.find_skillset(name)
+      errors << "SkillSet '#{name}' not found" unless ss
+
+      if ss
+        errors << "Not exchangeable: contains executable code" unless ss.exchangeable?
+
+        # Estimate archive size from file sizes (avoid packaging just to check)
+        estimated_size = estimate_archive_size(ss)
+        if estimated_size > @max_archive_size
+          errors << "Estimated archive too large (#{estimated_size} > #{@max_archive_size})"
+        end
+      end
+
+      { valid: errors.empty?, errors: errors }
+    end
+
+    private
+
+    # Estimate archive size from the sum of file sizes in the SkillSet.
+    # Tar overhead is ~512 bytes per entry; gzip typically compresses text well,
+    # so raw file size is a reasonable upper bound.
+    def estimate_archive_size(skillset)
+      Dir[File.join(skillset.path, '**', '*')]
+        .select { |f| File.file?(f) }
+        .sum { |f| File.size(f) }
+    rescue StandardError
+      Float::INFINITY  # fail-closed: unable to estimate size
+    end
+  end
+end