kairos-chain 3.6.0 → 3.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e63245a9c8dd3d8e79b83ad1eba7697cbf2075832b1afbae7080c4b1dea0e0de
-  data.tar.gz: 56ec7236649c644bd73fccbe35989640ac169831e8300531821c46ff01805475
+  metadata.gz: 70e5ff9eff0a25ceba4e38cf6bdb7f0c7fb45bd1f11b9345148625fe86b48be2
+  data.tar.gz: 7de3d8c8b819cc86ab3847a60250ecc98fe1bf66077a10a9f43521910f51480b
 SHA512:
-  metadata.gz: cb2ddc02ed24e10dcd76e6cf6f8149588b135011b8e777c52324961fc06ecb44a6810c1b97cdedda66bbcc8bcca484400a7f6a245dfbe7c1b831b7b2b0b04003
-  data.tar.gz: 455843011cef593d7ff7693d66f22be19dad14f70fe5b26cccc131cae903362089e35367e4410ba91138a9822b9b8adb6823f7ca98420bb6d9811e8f5233f106
+  metadata.gz: 4d8385510f0309d0705ac2a311da86f05c62332b77cf0f4cc7a0de7d271863f73e9137320d5d7470d5552c0b3da441500c178b7f3d5d8abd6e0b253ce7d562ed
+  data.tar.gz: f298792554a96d5da897523d9b6342d3fef2bc06e4d9a86d54a829c611fe5885fe6896168f7fc1853e3565bc2f4e71ed86d3740b39b898aaa4b0afc3c5337f4b

data/lib/kairos_mcp/version.rb

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

data/templates/skillsets/agent/config/agent.yml

@@ -39,5 +39,11 @@ tool_blacklist:
   - "mcp_connect"
   - "mcp_disconnect"
 
+# Additional tools available during ORIENT phase (opt-in from SkillSets).
+# Adding tools here increases the set the LLM can call during ORIENT;
+# the per-phase budget (max_tool_calls) is unchanged.
+orient_tools_extra: []
+  # - document_status   # uncomment to enable draft checking during ORIENT
+
 # Audit
 audit_level: summary

data/templates/skillsets/agent/test/test_agent_capability_discovery.rb

@@ -0,0 +1,307 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test suite for Agent Capability Discovery (orient_tools, build_tool_catalog)
+# Usage: ruby test_agent_capability_discovery.rb
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+$LOAD_PATH.unshift File.expand_path('../../../../lib', __dir__)
+
+require 'json'
+require 'yaml'
+require 'fileutils'
+require 'tmpdir'
+require 'kairos_mcp/invocation_context'
+require 'kairos_mcp/tools/base_tool'
+require 'kairos_mcp/tool_registry'
+require_relative '../lib/agent'
+require_relative '../tools/agent_start'
+require_relative '../tools/agent_step'
+
+$pass = 0
+$fail = 0
+
+def assert(description, &block)
+  result = block.call
+  if result
+    $pass += 1
+    puts "  PASS: #{description}"
+  else
+    $fail += 1
+    puts "  FAIL: #{description}"
+  end
+rescue StandardError => e
+  $fail += 1
+  puts "  FAIL: #{description} (#{e.class}: #{e.message})"
+end
+
+def section(title)
+  puts "\n#{'=' * 60}"
+  puts "TEST: #{title}"
+  puts '=' * 60
+end
+
+TMPDIR = Dir.mktmpdir('agent_cap_test')
+
+# Stubs
+module Autonomos
+  def self.storage_path(subpath)
+    path = File.join(TMPDIR, subpath)
+    FileUtils.mkdir_p(path)
+    path
+  end
+
+  module Mandate
+    def self.create(**kwargs); { mandate_id: 'test_mandate' }; end
+    def self.load(id); { mandate_id: id, max_cycles: 3, risk_budget: 'low', recent_gap_descriptions: [] }; end
+    def self.save(id, data); end
+    def self.update_status(id, status); end
+    def self.record_cycle(id, **kwargs); end
+    def self.risk_exceeds_budget?(proposal, budget); false; end
+    def self.loop_detected?(proposal, gaps); false; end
+    def self.check_termination(mandate); nil; end
+  end
+
+  module Ooda
+    def observe(goal_name); { 'status' => 'observed' }; end
+  end
+end
+
+module Autoexec
+  def self.config; {}; end
+  class TaskDsl
+    def self.from_json(json_string)
+      data = JSON.parse(json_string, symbolize_names: true)
+      data
+    end
+  end
+end
+
+Session = KairosMcp::SkillSets::Agent::Session
+
+# =========================================================================
+# Build test infrastructure
+# =========================================================================
+
+# Mock registry with some tools
+class CapTestRegistry
+  def initialize(tools = [])
+    @tools = tools
+  end
+
+  def list_tools
+    @tools
+  end
+
+  def call_tool(name, arguments, invocation_context: nil)
+    [{ text: '{}' }]
+  end
+end
+
+# Create an AgentStep instance with custom registry
+def build_agent_step(registry: nil, safety: nil)
+  step = KairosMcp::SkillSets::Agent::Tools::AgentStep.new(safety, registry: registry)
+  step
+end
+
+# Create a session with custom config
+def build_session(config_overrides = {})
+  config = {
+    'phases' => {},
+    'tool_blacklist' => %w[agent_* autonomos_*]
+  }.merge(config_overrides)
+
+  ctx = KairosMcp::InvocationContext.new(
+    blacklist: config['tool_blacklist'],
+    mandate_id: 'test_mandate'
+  )
+
+  Session.new(
+    session_id: "test_#{rand(10000)}",
+    mandate_id: 'test_mandate',
+    goal_name: 'test_goal',
+    invocation_context: ctx,
+    config: config
+  )
+end
+
+# =========================================================================
+# 1. orient_tools
+# =========================================================================
+
+section "orient_tools"
+
+assert("T1: returns base tools when no orient_tools_extra") do
+  step = build_agent_step
+  session = build_session
+  tools = step.send(:orient_tools, session)
+  tools.include?('knowledge_list') &&
+    tools.include?('resource_read') &&
+    tools.size == KairosMcp::SkillSets::Agent::Tools::AgentStep::BASE_ORIENT_TOOLS.size
+end
+
+assert("T2: merges orient_tools_extra from config") do
+  step = build_agent_step
+  session = build_session('orient_tools_extra' => ['document_status', 'custom_tool'])
+  tools = step.send(:orient_tools, session)
+  tools.include?('document_status') &&
+    tools.include?('custom_tool') &&
+    tools.include?('knowledge_list')
+end
+
+assert("T3: deduplicates entries") do
+  step = build_agent_step
+  session = build_session('orient_tools_extra' => ['knowledge_list', 'resource_read'])
+  tools = step.send(:orient_tools, session)
+  tools.count('knowledge_list') == 1
+end
+
+assert("handles nil session gracefully") do
+  step = build_agent_step
+  tools = step.send(:orient_tools, nil)
+  tools == KairosMcp::SkillSets::Agent::Tools::AgentStep::BASE_ORIENT_TOOLS
+end
+
+# =========================================================================
+# 2. build_tool_catalog
+# =========================================================================
+
+section "build_tool_catalog"
+
+SAMPLE_TOOLS = [
+  { name: 'write_section', description: 'Write a document section',
+    inputSchema: { type: 'object', properties: {}, required: %w[section_name instructions output_file] } },
+  { name: 'document_status', description: 'Show draft file inventory',
+    inputSchema: { type: 'object', properties: {}, required: %w[output_dir] } },
+  { name: 'knowledge_get', description: 'Get L1 knowledge',
+    inputSchema: { type: 'object', properties: {}, required: %w[name] } },
+  { name: 'agent_start', description: 'Start agent session',
+    inputSchema: { type: 'object', properties: {}, required: %w[goal_name] } },
+  { name: 'autonomos_loop', description: 'Run autonomos loop',
+    inputSchema: { type: 'object', properties: {} } }
+].freeze
+
+assert("T4: excludes blacklisted tools") do
+  registry = CapTestRegistry.new(SAMPLE_TOOLS)
+  step = build_agent_step(registry: registry)
+  session = build_session
+  catalog = step.send(:build_tool_catalog, session)
+  !catalog.include?('agent_start') && !catalog.include?('autonomos_loop')
+end
+
+assert("T5: includes non-blacklisted tools with descriptions and required params") do
+  registry = CapTestRegistry.new(SAMPLE_TOOLS)
+  step = build_agent_step(registry: registry)
+  session = build_session
+  catalog = step.send(:build_tool_catalog, session)
+  catalog.include?('write_section') &&
+    catalog.include?('section_name, instructions, output_file') &&
+    catalog.include?('document_status') &&
+    catalog.include?('knowledge_get')
+end
+
+assert("T6: returns fallback when no registry") do
+  step = build_agent_step(registry: nil)
+  session = build_session
+  catalog = step.send(:build_tool_catalog, session)
+  catalog.include?('no registry')
+end
+
+assert("T7: exact blacklist match works") do
+  tools = [{ name: 'skills_evolve', description: 'Evolve skills', inputSchema: {} }]
+  registry = CapTestRegistry.new(tools)
+  step = build_agent_step(registry: registry)
+  session = build_session('tool_blacklist' => %w[skills_evolve])
+  catalog = step.send(:build_tool_catalog, session)
+  !catalog.include?('skills_evolve')
+end
+
+assert("T8: wildcard blacklist via fnmatch works") do
+  tools = [
+    { name: 'chain_migrate_execute', description: 'Migrate', inputSchema: {} },
+    { name: 'chain_history', description: 'History', inputSchema: {} }
+  ]
+  registry = CapTestRegistry.new(tools)
+  step = build_agent_step(registry: registry)
+  session = build_session('tool_blacklist' => %w[chain_migrate_*])
+  catalog = step.send(:build_tool_catalog, session)
+  !catalog.include?('chain_migrate_execute') && catalog.include?('chain_history')
+end
+
+assert("handles namespaced tool names (basename blacklist)") do
+  tools = [{ name: 'peer1/agent_start', description: 'Remote agent start', inputSchema: {} }]
+  registry = CapTestRegistry.new(tools)
+  step = build_agent_step(registry: registry)
+  session = build_session  # blacklist includes agent_*
+  catalog = step.send(:build_tool_catalog, session)
+  # InvocationContext.allowed? checks basename — should be filtered
+  !catalog.include?('peer1/agent_start')
+end
+
+# =========================================================================
+# 3. extract_required_params
+# =========================================================================
+
+section "extract_required_params"
+
+assert("T11: handles symbol keys") do
+  step = build_agent_step
+  params = step.send(:extract_required_params, { required: %w[name version] })
+  params == %w[name version]
+end
+
+assert("T11b: handles string keys") do
+  step = build_agent_step
+  params = step.send(:extract_required_params, { 'required' => %w[output_dir] })
+  params == %w[output_dir]
+end
+
+assert("handles nil schema") do
+  step = build_agent_step
+  params = step.send(:extract_required_params, nil)
+  params == []
+end
+
+assert("handles schema without required") do
+  step = build_agent_step
+  params = step.send(:extract_required_params, { type: 'object', properties: {} })
+  params == []
+end
+
+# =========================================================================
+# 4. build_decide_prompt integration
+# =========================================================================
+
+section "build_decide_prompt integration"
+
+assert("T9: build_decide_prompt includes Available Tools section") do
+  registry = CapTestRegistry.new(SAMPLE_TOOLS)
+  step = build_agent_step(registry: registry)
+  session = build_session
+  orient_result = { 'content' => 'The goal requires writing a grant application.' }
+  prompt = step.send(:build_decide_prompt, session, orient_result)
+  prompt.include?('## Available Tools') &&
+    prompt.include?('write_section') &&
+    prompt.include?('Use ONLY tools listed above')
+end
+
+assert("T10: run_decide_with_feedback messages include catalog") do
+  # We can't easily run the full method (needs LLM), but we can verify
+  # the method exists and check the code path
+  step = build_agent_step(registry: CapTestRegistry.new(SAMPLE_TOOLS))
+  session = build_session
+  catalog = step.send(:build_tool_catalog, session)
+  catalog.include?('write_section') && catalog.include?('document_status')
+end
+
+# =========================================================================
+# Cleanup
+# =========================================================================
+
+FileUtils.rm_rf(TMPDIR)
+
+puts "\n#{'=' * 60}"
+puts "RESULTS: #{$pass} passed, #{$fail} failed (#{$pass + $fail} total)"
+puts '=' * 60
+
+exit($fail > 0 ? 1 : 0)

data/templates/skillsets/agent/tools/agent_step.rb

@@ -8,9 +8,9 @@ module KairosMcp
     module Agent
       module Tools
         class AgentStep < KairosMcp::Tools::BaseTool
-          ORIENT_TOOLS = %w[knowledge_list knowledge_get chain_history
-                            skills_list resource_list resource_read context_save
-                            mcp_list_remote].freeze
+          BASE_ORIENT_TOOLS = %w[knowledge_list knowledge_get chain_history
+                                skills_list resource_list resource_read context_save
+                                mcp_list_remote].freeze
 
           def name
             'agent_step'
@@ -150,7 +150,7 @@ module KairosMcp
             orient_prompt = build_orient_prompt(session, observation_text)
             messages = [{ 'role' => 'user', 'content' => orient_prompt }]
 
-            orient_result = loop_inst.run_phase('orient', orient_system_prompt, messages, ORIENT_TOOLS)
+            orient_result = loop_inst.run_phase('orient', orient_system_prompt, messages, orient_tools(session))
             return error_with_state(session, 'observed', orient_result) if orient_result['error']
 
             # DECIDE (single-stage; see design v0.4 sec 3.3 for future extension)
@@ -329,11 +329,16 @@ module KairosMcp
             prior_decision = session.load_decision
             prior_json = prior_decision ? JSON.generate(prior_decision) : '(none)'
 
+            # Include tool catalog so revise path has same tool awareness as initial DECIDE
+            catalog = build_tool_catalog(session)
+
             messages = [
               { 'role' => 'user', 'content' =>
+                "## Available Tools\n#{catalog}\n\n" \
                 "Previous plan:\n#{prior_json}\n\n" \
                 "This plan was rejected. Feedback: #{feedback}\n\n" \
-                "Please revise the plan and output a new decision_payload as JSON." }
+                "Please revise the plan and output a new decision_payload as JSON. " \
+                "Use ONLY tools listed above." }
             ]
             decide_result = loop_inst.run_decide(decide_system_prompt, messages)
             return error_with_state(session, 'proposed', decide_result) if decide_result['error']
@@ -442,8 +447,12 @@ module KairosMcp
 
           def build_decide_prompt(session, orient_result)
             analysis = orient_result['content'] || orient_result.to_json
+            catalog = build_tool_catalog(session)
+
             "Based on this analysis:\n#{analysis}\n\n" \
-            "Create a task execution plan as JSON (decision_payload format)."
+            "## Available Tools\n#{catalog}\n\n" \
+            "Create a task execution plan as JSON (decision_payload format). " \
+            "Use ONLY tools listed above."
           end
 
           def build_reflect_prompt(session, act_result)
@@ -452,6 +461,38 @@ module KairosMcp
             "Evaluate: what was achieved, what remains, confidence level (0.0-1.0)."
           end
 
+          # ---- Capability Discovery ----
+
+          # Config-driven ORIENT tools: base + optional extras from agent.yml
+          def orient_tools(session)
+            extra = session&.config&.dig('orient_tools_extra') || []
+            (BASE_ORIENT_TOOLS + extra).uniq
+          end
+
+          # Build a filtered tool catalog for DECIDE prompt.
+          # Uses session's InvocationContext.allowed? for blacklist/whitelist
+          # consistency with the ACT phase execution policy.
+          def build_tool_catalog(session)
+            return "(no registry available)" unless @registry
+
+            ctx = session&.invocation_context
+            tools = @registry.list_tools
+            tools = tools.reject { |t| ctx && !ctx.allowed?(t[:name]) } if ctx
+
+            tools.map { |t|
+              required = extract_required_params(t[:inputSchema])
+              params_str = required.empty? ? '' : " (params: #{required.join(', ')})"
+              "- **#{t[:name]}**#{params_str}: #{t[:description]}"
+            }.join("\n")
+          end
+
+          # Extract required parameter names from an inputSchema hash.
+          def extract_required_params(schema)
+            return [] unless schema.is_a?(Hash)
+            required = schema[:required] || schema['required'] || []
+            required.map(&:to_s)
+          end
+
           # ---- Helpers ----
 
           def load_last_decision(session)

data/templates/skillsets/document_authoring/config/document_authoring.yml

@@ -0,0 +1,22 @@
+# Document Authoring SkillSet configuration
+llm_model: null  # uses llm_client default
+
+# Output settings
+output_base_dir: null  # null = workspace root (@safety.safe_root)
+
+# Per-section limits
+max_words_default: 500
+
+# Context assembly
+max_context_chars: 4000        # per source, truncated at paragraph boundary
+max_total_context_chars: 16000  # total context budget
+max_context_sources: 10        # max number of context URIs
+
+# File safety
+allowed_output_extensions:
+  - ".md"
+  - ".txt"
+max_output_file_size_bytes: 1048576  # 1MB — refuse to overwrite larger files
+
+# document_status limits
+max_status_files: 50  # max files to scan

data/templates/skillsets/document_authoring/knowledge/agent_capability_document_authoring/agent_capability_document_authoring.md

@@ -0,0 +1,57 @@
+---
+tags: [agent-capability, document-authoring]
+version: "1.0"
+---
+
+# Agent Capability: Document Authoring
+
+## When to use
+
+The user asks to write, draft, or create structured documents such as:
+- Grant applications (e.g., UZH fellowship, SNF, ERC)
+- Research papers or manuscripts
+- Technical reports
+- Project proposals
+
+Keywords: write, draft, create, application, grant, paper, report, proposal, document
+
+## Tools
+
+- `write_section`: Write a document section using LLM with L1/L2 context injection
+- `document_status`: Check existing draft files and word counts
+
+## Typical task pattern
+
+```json
+{
+  "task_id": "write_grant_draft",
+  "meta": { "description": "Write grant application sections", "risk_default": "low" },
+  "steps": [
+    {
+      "step_id": "write_abstract",
+      "action": "Write project abstract",
+      "tool_name": "write_section",
+      "tool_arguments": {
+        "section_name": "abstract",
+        "instructions": "Write a concise project abstract covering motivation, approach, and expected impact",
+        "context_sources": ["knowledge://project_description"],
+        "output_file": "grant_draft/01_abstract.md",
+        "max_words": 250
+      },
+      "risk": "low", "depends_on": []
+    },
+    {
+      "step_id": "check_status",
+      "action": "Verify all sections written",
+      "tool_name": "document_status",
+      "tool_arguments": { "output_dir": "grant_draft/" },
+      "risk": "low", "depends_on": ["write_abstract"]
+    }
+  ]
+}
+```
+
+## Context sources
+
+Use `knowledge://` URIs for project-level context and `context://` URIs for
+session-specific context (e.g., previous grant feedback).

data/templates/skillsets/document_authoring/knowledge/document_authoring_guide/document_authoring_guide.md

@@ -0,0 +1,64 @@
+---
+tags: [document, authoring, grant, writing, agent, ooda]
+version: "1.0"
+---
+
+# Document Authoring Guide
+
+## Overview
+
+The `document_authoring` SkillSet provides LLM-driven document section generation
+with L1/L2 context injection. It integrates with the Agent SkillSet's OODA loop
+via autoexec's `internal_execute` dispatcher — no Agent or autoexec changes required.
+
+## Tools
+
+### write_section
+
+Generates a document section using an LLM, with optional context from L1 knowledge
+and L2 session contexts.
+
+```json
+{
+  "section_name": "research_significance",
+  "instructions": "Explain why genomic data ownership matters for open science",
+  "context_sources": ["knowledge://genomicschain_design"],
+  "output_file": "grant_draft/02_significance.md",
+  "max_words": 500,
+  "language": "en"
+}
+```
+
+### document_status
+
+Lists existing draft files with word counts. Non-recursive directory scan.
+
+```json
+{
+  "output_dir": "grant_draft/"
+}
+```
+
+## Agent Integration
+
+When used with the Agent SkillSet, the workflow is:
+
+1. Create L1 knowledge with the document goal (e.g., grant requirements)
+2. Start Agent session: `agent_start(goal_name: "grant_application_uzh")`
+3. Agent ORIENT identifies required sections from the goal
+4. Agent DECIDE generates task steps with `tool_name: "write_section"`
+5. Human approves the plan at [proposed] checkpoint
+6. Agent ACT executes write_section for each section via autoexec
+7. Agent REFLECT evaluates completeness
+
+## Context Sources
+
+Use the platform URI scheme:
+
+- `knowledge://genomicschain_design` — L1 knowledge
+- `context://session_id/context_name` — L2 session context
+
+## Output
+
+Generated text is written directly to the specified file (no JSON wrapper).
+Files are created under the workspace root with symlink-safe path validation.

data/templates/skillsets/document_authoring/lib/document_authoring/context_assembler.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  module SkillSets
+    module DocumentAuthoring
+      # Retrieves L1/L2 context via resource_read and assembles into prompt text.
+      # Uses the platform URI scheme (knowledge://, context://).
+      class ContextAssembler
+        # @param caller_tool [BaseTool] tool instance with invoke_tool access
+        # @param max_chars_per_source [Integer] max characters per source
+        # @param max_total_chars [Integer] total context budget
+        # @param max_sources [Integer] max number of sources
+        def initialize(caller_tool, max_chars_per_source: 4000,
+                       max_total_chars: 16_000, max_sources: 10)
+          @caller = caller_tool
+          @max_chars_per_source = max_chars_per_source
+          @max_total_chars = max_total_chars
+          @max_sources = max_sources
+        end
+
+        # Assemble context from resource URIs.
+        # @param sources [Array<String>] resource URIs (knowledge://, context://)
+        # @param context [Object, nil] InvocationContext for policy inheritance
+        # @return [Hash] { text: String, loaded: Integer, failed: Integer, warnings: Array<String> }
+        def assemble(sources, context: nil)
+          return { text: '', loaded: 0, failed: 0, warnings: [] } if sources.nil? || sources.empty?
+
+          warnings = []
+          texts = []
+          loaded = 0
+          failed = 0
+          total_chars = 0
+
+          if sources.size > @max_sources
+            warnings << "Truncated to #{@max_sources} sources (#{sources.size} provided)"
+          end
+
+          sources.first(@max_sources).each do |uri|
+            unless uri.match?(%r{\A(knowledge|context)://})
+              warnings << "Unknown URI scheme, skipped: #{uri}"
+              failed += 1
+              next
+            end
+
+            begin
+              result = @caller.invoke_tool('resource_read', { 'uri' => uri }, context: context)
+              text = extract_text(result)
+
+              if text.nil? || text.strip.empty?
+                warnings << "Empty content from: #{uri}"
+                failed += 1
+                next
+              end
+
+              truncated = truncate_at_paragraph(text, @max_chars_per_source)
+              remaining = @max_total_chars - total_chars
+              truncated = truncated[0...remaining] if truncated.length > remaining
+
+              texts << "### Source: #{uri}\n#{truncated}"
+              total_chars += truncated.length
+              loaded += 1
+            rescue StandardError => e
+              warnings << "Failed to load #{uri}: #{e.message}"
+              failed += 1
+            end
+
+            break if total_chars >= @max_total_chars
+          end
+
+          { text: texts.join("\n\n"), loaded: loaded, failed: failed, warnings: warnings }
+        end
+
+        private
+
+        def extract_text(result)
+          return '' unless result.is_a?(Array)
+
+          result.map { |b| b[:text] || b['text'] }.compact.join("\n")
+        end
+
+        def truncate_at_paragraph(text, max_chars)
+          return text if text.length <= max_chars
+
+          # Find last paragraph break (double newline) before max_chars
+          cut = text.rindex("\n\n", max_chars)
+          cut && cut > 0 ? text[0..cut] : text[0...max_chars]
+        end
+      end
+    end
+  end
+end