kairos-chain 3.6.1 → 3.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02a83d13eab2a28deb385acb5e3e57f62204923c2efe4f2768fcf063bca5def2
-  data.tar.gz: fcc519fed062416470e34d9fa95f1760b92ba61d8fb76b1f568a056e244f8c85
+  metadata.gz: 70e5ff9eff0a25ceba4e38cf6bdb7f0c7fb45bd1f11b9345148625fe86b48be2
+  data.tar.gz: 7de3d8c8b819cc86ab3847a60250ecc98fe1bf66077a10a9f43521910f51480b
 SHA512:
-  metadata.gz: fd5586084ac9d3b6faa446bd7471b9c812dfe6e506d52c6f00471100e8554ce1a7734001d9a0fc8ce715795bf82a606b3592d87d02812d5aeafa0db7ecd64325
-  data.tar.gz: fb0cc839b19d882bc89c1bcb1b3f95a9737f3d5000eeaf12a0fc6ed2927426d6d7b6d6084d5871a87a6ab362f5b533475d7e94cd13d473b6fb8982b91d82d647
+  metadata.gz: 4d8385510f0309d0705ac2a311da86f05c62332b77cf0f4cc7a0de7d271863f73e9137320d5d7470d5552c0b3da441500c178b7f3d5d8abd6e0b253ce7d562ed
+  data.tar.gz: f298792554a96d5da897523d9b6342d3fef2bc06e4d9a86d54a829c611fe5885fe6896168f7fc1853e3565bc2f4e71ed86d3740b39b898aaa4b0afc3c5337f4b

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.6.1"
+  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/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).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.6.1
+  version: 3.6.2
 platform: ruby
 authors:
 - Masaomi Hatakeyama
@@ -213,6 +213,7 @@ files:
 - templates/skillsets/agent/lib/agent/message_format.rb
 - templates/skillsets/agent/lib/agent/session.rb
 - templates/skillsets/agent/skillset.json
+- templates/skillsets/agent/test/test_agent_capability_discovery.rb
 - templates/skillsets/agent/test/test_agent_m1.rb
 - templates/skillsets/agent/test/test_agent_m2.rb
 - templates/skillsets/agent/test/test_agent_m3.rb
@@ -245,6 +246,7 @@ files:
 - templates/skillsets/autonomos/tools/autonomos_reflect.rb
 - templates/skillsets/autonomos/tools/autonomos_status.rb
 - templates/skillsets/document_authoring/config/document_authoring.yml
+- templates/skillsets/document_authoring/knowledge/agent_capability_document_authoring/agent_capability_document_authoring.md
 - templates/skillsets/document_authoring/knowledge/document_authoring_guide/document_authoring_guide.md
 - templates/skillsets/document_authoring/lib/document_authoring.rb
 - templates/skillsets/document_authoring/lib/document_authoring/context_assembler.rb