kairos-chain 3.42.1 → 3.43.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d6b5abadc2727f37c441c8d0442da6470438537ad47f387e6c4021769c678dd
-  data.tar.gz: f5c625947d73fb41251829cf638b397308294daa4fed7ed94cae945ad6086b72
+  metadata.gz: 4ef5b418a3202426bfd13d7f62a849363f52144978f6b091c9ebb8bb43564927
+  data.tar.gz: 471e635837cc5e5b65cd704dd78a9b48bd7312f61f7a27aa420c5323c5c0d43b
 SHA512:
-  metadata.gz: 4948c9a12280c2ccc7e0083e056d0ad99d457fcb11d86761f060a891d2033924395521364b5f867ca30eec2cc806f5d539ccc22282657c31e31a0695a5270f55
-  data.tar.gz: 789de8f265c7d1dbbde4969643e26f3359887b3417ddd76fe5567348b41c9dc8c37b2f062f6e77d382abc49becd4a2703ac4de29cf8d2f63b62c9fef272a5db1
+  metadata.gz: e45299ac0b7b574419742d6b8243fbd9b492641c37e5f5f1e81e22ea77623e2cf986ca96da63dfdde8cc5f08bef07ff83bb42ab816296c4fe50a002d80805ae5
+  data.tar.gz: 8138a96211b233b85f9e6342a32f2a02745dbf230ad319c274880c659c444ad03bf1909013864a79abeab2dccba7d754edbd3350506e7ffd751b112aac2803b0

data/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.42.2] - 2026-07-14
+
+### Knowledge — loop_engineering_patterns §B: Model/Effort budget allocation
+
+Extended the `loop_engineering_patterns` L1 entry (0.3 → 0.4) with a §B
+design-craft note distilled from Anthropic's *Model and Effort in Claude Code*
+post:
+
+- Model (intelligence ceiling) and effort (per-request thoroughness) are
+  distinct levers; raise model when logic/knowledge is the wall, raise effort
+  when the loop skips steps.
+- Because a loop compounds turns, uniform high effort multiplies latency —
+  concentrate high effort on the verify/judgment/decision gates, keep mechanical
+  dispatch turns low.
+- The lever is the *orchestrator's*; a worker in a separate process (hermes body
+  subprocess, `agent`-skillset step) carries its own config and is unaffected.
+- KairosChain delta: the non-bypassable gates (Prop 10 consent/audit floor,
+  INV-5 layer guard, verdict track) are where effort must not be cut — a stop
+  there is an irreversible Kairos moment (Prop 5), not a throughput step.
+
+Added the `effort-allocation` tag and a "high/low effort for a long run?"
+entry-point line. No code or behavior change.
+
 ## [3.42.1] - 2026-07-14
 
 ### Fixed — SectionWriter auto-chunk completeness & duplicate tail

data/lib/kairos_mcp/version.rb

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

data/templates/knowledge/loop_engineering_patterns/loop_engineering_patterns.md

@@ -1,8 +1,8 @@
 ---
 name: loop_engineering_patterns
 description: Use before designing or classifying an agent loop in KairosChain — to pick a loop type, apply loop-design craft, and place each loop at the right layer under the Prop 10 floor. Claude Code's four loop types + design principles, extended with the governance constraint Anthropic omits.
-version: "0.3"
-tags: [loops, agent, autonomy, taxonomy, layer-placement, provenance]
+version: "0.4"
+tags: [loops, agent, autonomy, taxonomy, layer-placement, provenance, effort-allocation]
 ---
 
 # Loop Engineering Patterns
@@ -14,6 +14,7 @@ Open *before* designing or classifying an agent loop — not a runtime tool:
 - New agent loop / autonomous cycle → pick a §A type, apply §B craft, then place it via §C.
 - "Which layer owns this loop?" (harness vs gem/SkillSet, plus the cross-cutting L0 governance floor) → §C table + the L0 note below it.
 - Strengthening the `agent` OODA loop (self-verification, semantic stop) → §B + §C evaluator/verifier notes.
+- "High/low effort for a long run?" → §B budget-allocation note (concentrate effort on §C's non-bypassable gates).
 - Explaining why KairosChain's autonomous mode keeps human checkpoints → §C Prop 10 floor.
 - Not for: skill lifecycle/maturation → [[agent_skill_evolution_guide]]; general layer rules → [[layer_placement_guide]].
 
@@ -29,6 +30,8 @@ Micro (small) and macro (broad) loops compose; match loop complexity to problem
 ## B. Design craft (universal — adopt as-is)
 Output quality tracks the surrounding harness, not the model alone. Keep the codebase clean so the loop follows existing patterns. **Encode verification as a skill with quantitative checks** so the loop measures its own work. Keep docs accessible/current. **Use a second, independent agent for review** (fresh context, separate session/model). Set explicit success/stop criteria and max-turn caps to bound cost; script deterministic steps instead of re-reasoning them; monitor token spend.
 
+**Allocate reasoning budget by phase, not uniformly.** Model and effort are distinct levers ([Model and Effort in Claude Code](https://claude.com/blog/claude-model-and-effort-level-in-claude-code), Anthropic, 2026): model sets the intelligence ceiling — raise it when logic or knowledge is the wall; effort sets per-request thoroughness (files read, tests run, verification passes) — raise it when the loop skips steps, not when it lacks intelligence. Because a loop compounds turns, uniform high effort multiplies latency across every cycle: concentrate high effort on the verify / judgment / decision gates and keep mechanical dispatch turns low. Note this is the *orchestrator's* lever — it governs how carefully the loop monitors, verifies, and decides; it does not raise the quality of a worker running in a separate process (e.g. a hermes body subprocess or an `agent`-skillset step), which carries its own model/effort config. In KairosChain the non-bypassable gates — the Prop 10 consent/audit floor, the INV-5 layer guard, the verdict track — are exactly where effort must not be cut, since a stop there is an irreversible Kairos moment (§C, Prop 5), not a throughput step.
+
 ## C. KairosChain reading (layer placement + the floor Anthropic omits)
 The four types are harness-framed (`/goal`, `/loop`, `/schedule`, `/usage`, auto mode are Claude Code mechanisms). KairosChain already implements most of the substance across layers — so the work is mostly *placement*, not adoption; one item is still design-stage (flagged in the table):
 

data/templates/skillsets/hestia/config/hestia.yml

@@ -13,6 +13,30 @@ meeting_place:
   # registry_path: storage/agent_registry.json
   # parent_place_url: null  # URL of parent place for federation
 
+  # Public web surface (unauthenticated, read-only): skill catalog, JSON API,
+  # and — when anchoring is enabled — the ANC-7 verification view.
+  # Mounted by PlaceRouter under /place/web/* and /place/api/v1/*.
+  web_ui:
+    enabled: true
+    # place_host / place_url anchor the public links and the ANC-7 verification
+    # address (place://<place_host>/anchor/<slug>). Set to the served hostname.
+    # place_host: meeting.genomicschain.io
+    # place_url: https://meeting.genomicschain.io
+
+  # Anchor attestation capability (ANC-1..9 / BRD-1..4). Opt-in: when disabled
+  # the catalog still serves but /place/web/verify and /place/web/anchor/* 404.
+  # Enable on the place that hosts external-reference (content-by-reference)
+  # anchors — e.g. the constitutive-note / GenomicsChain provenance deployment.
+  anchoring:
+    enabled: false
+    # ANC-9 free-write budget (mechanism, design §11) — tune to observed load.
+    # The Sybil disclosure is shown regardless of the numbers.
+    per_identity: 60      # writes per identity per window
+    aggregate: 600        # writes across all identities per window
+    window_seconds: 3600  # refill window
+    # log_path: storage/hestia_anchor_log.json
+    # attestation_store_path: storage/hestia_anchor_attestations.json
+
   # Deposit policy (operator-configurable)
   deposit_policy:
     max_skill_size_bytes: 100000

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Hestia
+  # Generates shell-safe import commands for various LLM tools.
+  # All interpolated values are escaped via Shellwords.shellescape.
+  class ImportCommandGenerator
+    def initialize(place_url:)
+      @place_url = place_url
+    end
+
+    def commands_for(skill, deposit_id:)
+      safe_url = Shellwords.shellescape(@place_url)
+      safe_skill_id = Shellwords.shellescape(skill[:skill_id] || deposit_id.split('__', 2).last)
+
+      {
+        claude_code: claude_code_command(safe_skill_id, safe_url),
+        codex: codex_command(safe_skill_id, safe_url),
+        kairos_cli: kairos_cli_command(safe_skill_id, safe_url),
+        curl_preview: curl_preview_command(Shellwords.shellescape(deposit_id), safe_url)
+      }
+    end
+
+    private
+
+    def claude_code_command(skill_id, place_url)
+      "claude -p \"Use meeting_acquire_skill to acquire #{skill_id} from place #{place_url}\""
+    end
+
+    def codex_command(skill_id, place_url)
+      "echo \"Use meeting_acquire_skill to acquire #{skill_id} from place #{place_url}\" | codex exec -"
+    end
+
+    def kairos_cli_command(skill_id, place_url)
+      "kairos-chain acquire --place #{place_url} --skill #{skill_id}"
+    end
+
+    def curl_preview_command(deposit_id, place_url)
+      "curl -s #{place_url}/place/api/v1/skill/#{deposit_id}"
+    end
+  end
+end

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

@@ -55,7 +55,8 @@ module Hestia
       end
     end
 
-    attr_reader :registry, :skill_board, :heartbeat_manager, :session_store, :started_at, :extensions
+    attr_reader :registry, :skill_board, :heartbeat_manager, :session_store, :started_at, :extensions,
+                :web_router, :anchor_log, :anchor_board
 
     def initialize(config: nil)
       @config = config || ::Hestia.load_config
@@ -63,6 +64,16 @@ module Hestia
       @skill_board = nil
       @heartbeat_manager = nil
       @session_store = nil
+      # The public (unauthenticated) web UI + JSON API + ANC-7 verification view.
+      # Constructed in #start when the operator enables it (default on). The
+      # Meeting Place SkillSet owns its own public surface here rather than in the
+      # core HTTP server, so mounting it never crosses the L0/SkillSet boundary.
+      @web_router = nil
+      # Anchor store instances (nil until #start with anchoring enabled). Exposed
+      # so an authenticated write entry point can deposit into the same log/board
+      # the public ANC-7 view reads from.
+      @anchor_log = nil
+      @anchor_board = nil
       @started = false
       @started_at = nil
       @self_id = nil
@@ -121,6 +132,16 @@ module Hestia
         observer_id: @self_id
       )
 
+      # Anchor store (ANC-1 log + BRD board + ANC-9 budget). Built independently
+      # of the web UI so it also backs the authenticated write path (the
+      # inaugural / external anchoring deposit), and exposed via attr_reader so an
+      # operator write entry point deposits into the same instances the public
+      # view reads from. [nil, nil] when anchoring is disabled.
+      @anchor_log, @anchor_board = build_anchor_store(place_config, default_storage)
+
+      # Mount the public web surface (catalog/api + ANC-7 verification view).
+      @web_router = build_web_router(place_config)
+
       # Self-register: the Place IS also a participant (主客未分)
       @registry.self_register(identity)
 
@@ -135,6 +156,84 @@ module Hestia
       }
     end
 
+    # Build the public WebRouter (catalog/api + ANC-7 verification view).
+    #
+    # The web classes require rack/utils (present in the server bundle) and are
+    # required lazily here so a place that never serves the web UI does not pull
+    # in rack at load time. A missing dependency degrades to "web UI not mounted"
+    # (the authenticated API keeps working) rather than a boot failure.
+    #
+    # @return [WebRouter, nil] nil when disabled or the dependency is unavailable.
+    def build_web_router(place_config)
+      web_config = place_config['web_ui'] || {}
+      return nil unless web_config.fetch('enabled', true)
+
+      require_relative 'public_rate_limiter'
+      require_relative 'public_presenter'
+      require_relative 'import_command_generator'
+      require_relative 'web_router'
+
+      place_host = web_config['place_host']
+      place_url = web_config['place_url'] || (place_host && "https://#{place_host}")
+
+      WebRouter.new(
+        skill_board: @skill_board,
+        agent_registry: @registry,
+        config: {
+          'name' => place_config['name'] || 'KairosChain Meeting Place',
+          'place_host' => place_host,
+          'place_url' => place_url
+        }.compact,
+        anchor_read: build_anchor_read
+      )
+    rescue LoadError => e
+      warn "[PlaceRouter] Public web UI not mounted (missing dependency): #{e.message}"
+      nil
+    end
+
+    # Build the Synoptis-owned public read handle the WebRouter presents through
+    # (AHM-1). nil when anchoring is disabled (@anchor_log unset), in which case
+    # the anchor routes 404. The write-side handles (@anchor_log/@anchor_board)
+    # stay owned here for the authenticated deposit path (design §4.3).
+    def build_anchor_read
+      return nil unless @anchor_log
+
+      Synoptis::Anchoring::PublicRead.new(log: @anchor_log, board: @anchor_board)
+    end
+
+    # Build the anchor store (ANC-1 log + BRD deposit board + ANC-9 write budget)
+    # when the operator enables anchoring. Returns [nil, nil] when disabled, in
+    # which case the WebRouter serves the catalog but the /place/web/verify and
+    # /place/web/anchor/* routes 404 (the capability is simply not present).
+    #
+    # The operator identity (@self_id) is the ANC-5/ANC-8 control boundary: it is
+    # the only identity permitted to withdraw any entry and the one against which
+    # same-party vs foreign is derived.
+    def build_anchor_store(place_config, default_storage)
+      anchor_config = place_config['anchoring'] || {}
+      return [nil, nil] unless anchor_config['enabled']
+
+      require 'synoptis'
+
+      log = Synoptis::Anchoring::Log.new(
+        storage_path: anchor_config['log_path'] || "#{default_storage}hestia_anchor_log.json",
+        operator_id: @self_id
+      )
+      budget = Synoptis::Anchoring::WriteBudget.new(
+        per_identity: anchor_config['per_identity'] || Synoptis::Anchoring::WriteBudget::DEFAULT_PER_IDENTITY,
+        aggregate: anchor_config['aggregate'] || Synoptis::Anchoring::WriteBudget::DEFAULT_AGGREGATE,
+        window_seconds: anchor_config['window_seconds'] || Synoptis::Anchoring::WriteBudget::DEFAULT_WINDOW_SECONDS,
+        operator_id: @self_id
+      )
+      board = Synoptis::Anchoring::DepositBoard.new(
+        log: log,
+        attestation_store_path: anchor_config['attestation_store_path'] ||
+          "#{default_storage}hestia_anchor_attestations.json",
+        budget: budget
+      )
+      [log, board]
+    end
+
     # Rack-compatible call method.
     def call(env)
       unless @started
@@ -147,6 +246,16 @@ module Hestia
       request_method = env['REQUEST_METHOD']
       path = env['PATH_INFO']
 
+      # Public, unauthenticated, read-only web surface (ANC-7 verification view,
+      # skill catalog, JSON API). Delegated before the auth flow — same position
+      # as the other unauthenticated endpoints below. The WebRouter enforces
+      # GET-only, IP rate limiting, and HTML escaping internally.
+      if @web_router &&
+         (path == '/place/web' || path.start_with?('/place/web/') ||
+          path.start_with?('/place/api/v1/'))
+        return @web_router.call(env)
+      end
+
       # Unauthenticated endpoints
       if request_method == 'GET' && path == '/place/v1/info'
         return handle_info

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Hestia
+  # Shared presenter for public data — used by both JSON API and HTML views.
+  # Truncates IDs and strips content to prevent information leakage.
+  class PublicPresenter
+    ID_TRUNCATE_LENGTH = 12
+
+    def catalog_entry(entry, auditor = nil)
+      deposit_id = make_deposit_id(entry)
+      {
+        deposit_id: deposit_id,
+        skill_id: entry[:skill_id],
+        name: entry[:name],
+        description: truncate(entry[:description], 500),
+        tags: entry[:tags] || [],
+        format: entry[:format],
+        type: entry[:type],
+        size_bytes: entry[:size_bytes],
+        content_hash: entry[:content_hash]&.slice(0, 16),
+        deposited_at: entry[:deposited_at],
+        depositor_id: truncate_id(entry[:agent_id] || entry[:depositor_id]),
+        summary: truncate(entry[:summary], 500),
+        version: entry[:version],
+        license: entry[:license],
+        attestation_count: entry[:attestations]&.size || 0,
+        audit_status: auditor ? auditor.audit_status(deposit_id)[:status] : nil
+      }
+    end
+
+    def skill_detail(skill, auditor = nil)
+      base = catalog_entry(skill, auditor)
+      base.merge(
+        sections: skill[:sections],
+        first_lines: skill[:first_lines],
+        input_output: skill[:input_output],
+        attestations: present_attestations(skill[:attestations]),
+        trust_notice: skill[:trust_notice],
+        audit_detail: auditor ? auditor.audit_status(make_deposit_id(skill)) : nil
+      )
+    end
+
+    def agent_profile(agent)
+      id = agent.respond_to?(:id) ? agent.id : agent[:id]
+      {
+        agent_id: truncate_id(id),
+        name: agent.respond_to?(:name) ? agent.name : agent[:name],
+        description: agent.respond_to?(:description) ? agent.description : agent[:description],
+        registered_at: agent.respond_to?(:registered_at) ? agent.registered_at : agent[:registered_at]
+      }
+    end
+
+    def make_deposit_id(entry)
+      agent = entry[:agent_id] || entry[:depositor_id]
+      skill = entry[:skill_id]
+      "#{agent}__#{skill}" if agent && skill
+    end
+
+    private
+
+    def present_attestations(attestations)
+      return [] unless attestations
+
+      attestations.map do |a|
+        {
+          claim: a[:claim],
+          attester_id: truncate_id(a[:attester_id]),
+          attester_name: a[:attester_name],
+          actor_role: a[:actor_role],
+          has_signature: a[:has_signature],
+          deposited_at: a[:deposited_at]
+        }
+      end
+    end
+
+    def truncate_id(id)
+      return nil unless id
+      id.length > ID_TRUNCATE_LENGTH ? "#{id[0, ID_TRUNCATE_LENGTH]}..." : id
+    end
+
+    def truncate(text, max)
+      return nil unless text
+      text.length > max ? "#{text[0, max]}..." : text
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hestia
+  # IP-based rate limiter for public web/API endpoints.
+  # Bounded memory: TTL eviction + max tracked IPs.
+  class PublicRateLimiter
+    MAX_REQUESTS_PER_MINUTE = 30
+    MAX_TRACKED_IPS = 10_000
+    CLEANUP_INTERVAL = 1000
+    STALE_SECONDS = 300
+
+    def initialize(max_rpm: MAX_REQUESTS_PER_MINUTE)
+      @max_rpm = max_rpm
+      @requests = {}
+      @mutex = Mutex.new
+      @total_requests = 0
+    end
+
+    def allow?(ip)
+      @mutex.synchronize do
+        @total_requests += 1
+        cleanup! if (@total_requests % CLEANUP_INTERVAL).zero?
+
+        now = Time.now.to_f
+        @requests[ip] = (@requests[ip] || []).select { |t| now - t < 60 }
+
+        return false if @requests[ip].size >= @max_rpm
+
+        @requests[ip] << now
+        true
+      end
+    end
+
+    private
+
+    def cleanup!
+      now = Time.now.to_f
+      @requests.delete_if { |_ip, timestamps| timestamps.all? { |t| now - t >= STALE_SECONDS } }
+
+      return unless @requests.size > MAX_TRACKED_IPS
+
+      sorted = @requests.sort_by { |_ip, ts| ts.last || 0 }
+      excess = @requests.size - MAX_TRACKED_IPS
+      sorted.first(excess).each { |ip, _| @requests.delete(ip) }
+    end
+  end
+end