kairos-chain 3.91.0 → 3.92.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8edb08c26be7f068db03e377e1f9d48ba67135b233dfa16f0fab9e7126364bca
-  data.tar.gz: 81557a33e8214065bf3e692948b58e3655e0758f5b95e13ae19c9bcc67c4cf17
+  metadata.gz: 3cea3a83409113bb9513f6da35f8e202ed84762f726997b55d4c0807e3764565
+  data.tar.gz: e88354debd6836834ffcf28b905f361b4e9d0d154d22d68f6112a20076fc45c1
 SHA512:
-  metadata.gz: a6fbd7b1e9a1a347f941d292c6b0b55c8801b8ca609503281721d175a7567f27e2b20791ded6b2404eefbc3c6d7d8e84b16f3136fa0faffdad39d3bed574b044
-  data.tar.gz: fcff23454d07a3720ddb982a421137b292e9844228276e445181062ec64ac06025bf4cc4d0afe6c5be4202d889f1b8ddacf10eaa3859cc87ee2d998e627789d4
+  metadata.gz: 811debe565ba6b2815b24860edc7d43a1cec1f3c0da9a8b4d4aed0c52d88052ddbd8f53b544575b253860da2ad669d197f9c5a105ffdc08a8d8e9fb002aade2b
+  data.tar.gz: 9682dc5d58a0264960323374db889ad4074e0c063685a0062866e811ec04eb1c91a94fef720a4260b58f69d26f12f9640087213c713dc8c9c1438fb0f836089f

data/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.92.0] - 2026-10-13
+
+### Added — agent: judgment precedents the shadow judge reads, distilled from your answers
+
+The shadow judge is a fresh model at every point, so it does not improve with
+use. It can now also read an instance L1 entry, `agent_judgment_precedents`,
+that generalizes your terminal answers and their reasons. The entry is drafted
+by a separate model and reaches the judge only after you adopt it at the
+terminal. **The judge's answer still changes nothing**; every row stays
+`shadow`.
+
+- **What the driver records**: when an answer at either point commits, the
+  plans it covered are filed in the session (`point_facts.jsonl`), fixed at
+  the moment you answered (an approve at an autonomous checkpoint never
+  covers the cycles it starts): each step's tool name and effect where the
+  act-route table classified it, counts elsewhere. A step the table does not classify is never named. The ruling
+  carries the digest of the filed line.
+- **Drafting**: after ten new answers you typed at the terminal with a reason,
+  a separate process (`bin/agent_distill.rb`, `claude-opus-5-5` at `xhigh`
+  through `llm_call`, sandboxed) drafts the entry again from all your attested
+  answers, their terminal reasons, the filed facts and your edits to earlier
+  drafts. It never reads the agent's text, the judge's verdicts or an earlier
+  entry. Every statement names the answers it rests on, all at one point,
+  and its count and that point's totals are computed by code. It runs only while the delegation table is in force, one
+  at a time, off the answer path; a failure waits for ten more answers. The
+  draft is recorded on the chain (`agent_distill_draft`).
+- **Adoption**: edit the draft's `.edit.md` copy under
+  `.kairos/storage/agent_distill/drafts/`, then
+  `ruby .kairos/skillsets/agent/bin/agent_rule.rb adopt`. It checks the draft
+  against its chain record, refuses while any session is mid-run (checked
+  again after you confirm), shows your changes and the difference from the
+  entry in force, asks for the nonce, and records one delegation ruling that
+  pins exactly the bytes adopted; on any failure or interrupt the previous
+  entry is put back. When the entry has left its pin (an interrupted
+  adoption, a hand edit), adoption is also the way back. `agent_rule.rb
+  distill` drafts now, whatever the count; `agent_rule.rb status` shows the
+  count, the last run and waiting drafts.
+- **Only adoption pins new precedents**: any other ruling of the delegation
+  table refuses while the entry differs from its last pin.
+- **Counting per version**: `agent_rule.rb shadow` reports agreement apart for
+  each combination of the two tables, what the judge read and the judge's own
+  prompt (now carried on every seal as `judge_prompt_sha256`). A new adoption
+  or an instruction-mode edit starts a new count.
+- The terminal's reason prompt now says that reasons may be distilled into
+  this entry, which the agent can read.
+
+**After upgrading, rule the delegation table again** where it was in force:
+the shipped table now names `judgment_precedents`, so the judge stops (hash
+mismatch) until you run
+`ruby .kairos/skillsets/agent/bin/agent_rule.rb activate --table delegation`,
+which pins the entry as absent. An instance with no delegation ruling is
+unaffected and drafts nothing.
+
 ## [3.91.0] - 2026-10-07
 
 ### Added — agent: a shadow judge beside the operator (approval delegation, phase 1)

data/lib/kairos_mcp/version.rb

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

data/templates/skillsets/agent/bin/agent_distill.rb

@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# The distiller's process (distillation design v0.2, INV-K1 / INV-K4).
+# Started detached by the driver after an attested, reasoned answer at a
+# delegable point commits, or in the foreground by `agent_rule.rb distill`.
+# Counting, the one-draft lock, the table's status and the inputs are all
+# decided here, off the response path; DistillRun does the run.
+#
+# It loads no agent tool and never opens a session's advance lock. What it
+# reads is what the operator authored and what the driver observed: the
+# attested answers on the chain, the terminal-sourced reasons they name, the
+# point facts they name, and the operator's changes recorded at adoption.
+#
+# The model is reached through llm_call as the shadow judge reaches it:
+# provider claude_code with sandbox_mode, no fallback.
+#
+# argv: [--manual]   run whatever the count (the operator asked for it)
+# env:  KAIROS_SERVER_LIB   lib dir to load kairos_mcp from
+#       KAIROS_DATA_DIR     the server's data dir (the chain read and written)
+#       KAIROS_PROJECT_ROOT the server's working directory (its .kairos/storage)
+
+require 'json'
+
+manual = ARGV.include?('--manual')
+
+begin
+  Process.setsid unless manual
+rescue StandardError
+  # Already a group leader (spawned with pgroup): acceptable.
+end
+
+begin
+  Dir.chdir(ENV['KAIROS_PROJECT_ROOT']) if ENV['KAIROS_PROJECT_ROOT'] && Dir.exist?(ENV['KAIROS_PROJECT_ROOT'])
+  $LOAD_PATH.unshift(ENV['KAIROS_SERVER_LIB']) if ENV['KAIROS_SERVER_LIB'] && !ENV['KAIROS_SERVER_LIB'].empty?
+  require 'kairos_mcp'
+  KairosMcp.data_dir = ENV['KAIROS_DATA_DIR'] if ENV['KAIROS_DATA_DIR'] && !ENV['KAIROS_DATA_DIR'].empty?
+  require 'kairos_mcp/kairos_chain/chain'
+
+  lib = File.expand_path('../lib', __dir__)
+  %w[session admission mandate_adapter act_classification answer_ruling delegation point_facts distiller
+     distill_run distiller_prompt].each { |f| require File.join(lib, 'agent', f) }
+  require 'kairos_mcp/tools/base_tool'
+  # agent depends on llm_client; both are installed side by side.
+  require File.expand_path('../../llm_client/tools/llm_call', __dir__)
+rescue ScriptError, StandardError => e
+  warn JSON.generate({ 'status' => 'failed', 'reason' => "bootstrap: #{e.class}: #{e.message[0, 200]}" })
+  exit 1
+end
+
+agent = KairosMcp::SkillSets::Agent
+ar = agent::AnswerRuling
+pf = agent::PointFacts
+sessions = agent::Session.storage_path('agent_sessions')
+dir = agent::Session.storage_path('agent_distill')
+
+session_dir = lambda do |sid|
+  next nil unless sid.to_s.match?(/\A[\w-]+\z/)
+
+  d = File.join(sessions, sid.to_s)
+  File.directory?(d) ? d : nil
+end
+
+# The reason the operator typed at the terminal, matched by the digest the
+# ruling names. A caller's text is never the operator's reason.
+reason = lambda do |sid, anchor, sha|
+  d = session_dir.call(sid)
+  next nil unless d
+
+  ar.texts_at(d, anchor, source: 'terminal').map { |t| t['rationale'] }.find { |r| r && ar.sha256(r) == sha }
+end
+
+# The plans the answer covered, as the driver filed them when the answer
+# committed; nil unless the filed line is the one the ruling names. An answer
+# at a point always covers a plan, so an empty window is facts not recorded.
+# Only what the driver observed passes: the cycle, and per step the tool and
+# effect the table gave it, the unclassified count and the step count. The
+# plan's own marks for a person are the agent's declaration and stay behind.
+facts = lambda do |sid, anchor, sha|
+  d = session_dir.call(sid)
+  next nil unless d
+
+  entry, line_sha = pf.answer_facts(d, anchor)
+  plans = entry && line_sha == sha ? entry['plans'] : nil
+  next nil unless plans.is_a?(Array) && !plans.empty?
+  next nil unless plans.all? { |p| p.is_a?(Hash) && p['facts'].is_a?(Hash) }
+
+  plans.map do |p|
+    f = p['facts']
+    { 'cycle' => p['cycle'], 'facts' => f.slice('steps', 'unclassified', 'step_count') }
+  end
+end
+
+edits = Dir.glob(File.join(dir, 'adoptions', '*.json')).sort.filter_map do |f|
+  e = JSON.parse(File.read(f))
+  e.is_a?(Hash) ? e.slice('adopted_block', 'changes') : nil
+rescue StandardError
+  nil
+end.sort_by { |e| e['adopted_block'].to_i }
+
+llm = lambda do |system:, user:, model:, effort:, provider:|
+  out = KairosMcp::SkillSets::LlmClient::Tools::LlmCall.new(nil).call(
+    'messages' => [{ 'role' => 'user', 'content' => user }], 'system' => system, 'model' => model,
+    'effort' => effort, 'sandbox_mode' => true, 'provider_override' => provider
+  )
+  payload = JSON.parse(Array(out).first[:text])
+  raise "llm_call #{payload.dig('error', 'type')}: #{payload.dig('error', 'message')}" unless payload['status'] == 'ok'
+
+  payload['response'].merge('provider' => payload['provider'])
+end
+
+records, records_error = ar.chain_records
+if records_error
+  warn JSON.generate({ 'status' => 'failed', 'reason' => "chain unreadable: #{records_error}" })
+  exit 1
+end
+
+result = agent::DistillRun.run(
+  dir: dir, delegation_status: agent::Delegation.load_effective['status'], records: records,
+  facts: facts, reason: reason, edits: edits, llm: llm, chain: KairosMcp::KairosChain::Chain.new,
+  judge: agent::Delegation::JUDGE, prompts: agent::DistillerPrompt, manual: manual
+)
+(manual ? $stdout : $stderr).puts JSON.generate(result)
+exit(%w[failed].include?(result['status']) ? 1 : 0)

data/templates/skillsets/agent/bin/agent_rule.rb

@@ -11,7 +11,12 @@
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb answer SESSION_ID
 #                         # answer a stopped session; the MCP answer there must then match
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb shadow     # count the shadow judge's agreement
-#                                                             # with your answers (records nothing)
+#                                                             # with your answers, per version of what
+#                                                             # shaped the judge (records nothing)
+#   ruby .kairos/skillsets/agent/bin/agent_rule.rb distill    # draft judgment precedents now, whatever
+#                                                             # the count (calls the distiller model)
+#   ruby .kairos/skillsets/agent/bin/agent_rule.rb adopt [STAMP]
+#                         # adopt a draft (the newest by default) after editing its .edit.md copy
 #
 # Options: --table NAME       activate / withdraw: act_classification (default)
 #                             or delegation
@@ -23,7 +28,7 @@
 #                             Needed when the server runs with --data-dir
 #                             pointing at another project's .kairos.
 #
-# activate, withdraw and answer read a nonce typed back at /dev/tty and refuse to run
+# activate, withdraw, answer and adopt read a nonce typed back at /dev/tty and refuse to run
 # without a terminal. That keeps an MCP call from producing a ruling through
 # this path. It does not prove a person typed: any process that can start
 # programs can open a pseudo-terminal, read the nonce and type it back (shown
@@ -32,12 +37,15 @@
 # was at the keyboard (INV-D8 boundary; the constrained party is the agent).
 
 require 'json'
+require 'rbconfig'
 
-action = ARGV.find { |a| %w[activate withdraw status answer shadow].include?(a) }
-abort 'usage: agent_rule.rb activate|withdraw [--table act_classification|delegation]|status|answer SESSION_ID|shadow ' \
-      '[--data-dir DIR] [--project-dir DIR]' unless action
+action = ARGV.find { |a| %w[activate withdraw status answer shadow distill adopt].include?(a) }
+abort 'usage: agent_rule.rb activate|withdraw [--table act_classification|delegation]|status|answer SESSION_ID|shadow|' \
+      'distill|adopt [STAMP] [--data-dir DIR] [--project-dir DIR]' unless action
 session_id = action == 'answer' ? ARGV[ARGV.index('answer') + 1].to_s : nil
 abort 'usage: agent_rule.rb answer SESSION_ID [--data-dir DIR]' if session_id&.then { |s| s.empty? || s.start_with?('-') }
+stamp = action == 'adopt' ? ARGV[ARGV.index('adopt') + 1] : nil
+stamp = nil if stamp.to_s.start_with?('-')
 
 tidx = ARGV.index('--table')
 table = tidx ? ARGV[tidx + 1].to_s : 'act_classification'
@@ -63,12 +71,16 @@ require File.join(lib, 'agent', 'act_classification')
 require File.join(lib, 'agent', 'answer_ruling')
 require File.join(lib, 'agent', 'delegation')
 require File.join(lib, 'agent', 'shadow_judge')
+require File.join(lib, 'agent', 'point_facts')
+require File.join(lib, 'agent', 'distiller')
+require File.join(lib, 'agent', 'distill_run')
+require File.join(lib, 'agent', 'adoption')
 ac = KairosMcp::SkillSets::Agent::ActClassification
 dl = KairosMcp::SkillSets::Agent::Delegation
 path = ac::BASE_PATH
 
 puts "Data dir: #{data_dir}"
-if %w[answer shadow].include?(action)
+if %w[answer shadow status distill adopt].include?(action)
   require 'kairos_mcp/invocation_context'
   require File.join(lib, 'agent', 'session')
   require File.join(lib, 'agent', 'advance_gate')
@@ -77,7 +89,9 @@ if %w[answer shadow].include?(action)
   # data dir. The two can differ; the answer is read from the first and
   # recorded on the second, the chain the server reads.
   pidx = ARGV.index('--project-dir')
-  abort 'usage: agent_rule.rb answer SESSION_ID --project-dir DIR' if pidx && ARGV[pidx + 1].to_s.then { |v| v.empty? || v.start_with?('-') }
+  if pidx && ARGV[pidx + 1].to_s.then { |v| v.empty? || v.start_with?('-') }
+    abort "usage: agent_rule.rb #{action == 'answer' ? 'answer SESSION_ID' : action} --project-dir DIR"
+  end
   project_dir = pidx ? File.expand_path(ARGV[pidx + 1].to_s) : File.dirname(data_dir)
   abort "no project dir at #{project_dir}" unless File.directory?(project_dir)
   Dir.chdir(project_dir)
@@ -102,9 +116,45 @@ if action == 'status'
   puts "  file sha256:  #{deff['sha256']}"
   puts "  detail: #{deff['detail']}" if deff['detail']
   deff['rows'].each { |r| puts "  row #{r['id']} at #{r['point']} (#{r['mode']})" }
-  deff['reads'].each { |p| puts "  judge reads #{p['name']}: #{p['path']} (sha256 #{p['sha256']})" }
+  deff['reads'].each do |p|
+    puts(p['absent'] ? "  judge reads #{p['name']}: #{p['path']} (absent: nothing adopted yet)" :
+                       "  judge reads #{p['name']}: #{p['path']} (sha256 #{p['sha256']})")
+  end
+  # Drafting (distillation design v0.2 INV-K4): shown here, never in an advance.
+  distill_dir = KairosMcp::SkillSets::Agent::Session.storage_path('agent_distill')
+  drun = KairosMcp::SkillSets::Agent::DistillRun
+  st = drun.state(distill_dir)
+  records, rerr = KairosMcp::SkillSets::Agent::AnswerRuling.chain_records
+  counted = rerr ? "unknown (#{rerr})" :
+                   KairosMcp::SkillSets::Agent::Distiller.count_new(records, high_water: st['high_water'].to_i)
+  puts 'Judgment precedents drafting:'
+  puts "  reasoned answers since the last draft: #{counted} (a draft starts at #{KairosMcp::SkillSets::Agent::Distiller::THRESHOLD}; " \
+       "only while the delegation table is in force)"
+  last = st['last'] || {}
+  puts "  last run: #{last.empty? ? '(none)' : last.map { |k, v| "#{k} #{v}" }.join(', ')}"
+  if last['status'] == 'running'
+    # A run holds the lock for its whole life; a free lock means it died.
+    # Read the state again while holding the lock: a run that finished in
+    # between released it, and is not dead.
+    died = File.open(File.join(distill_dir, drun::LOCK_FILE), 'a') do |f|
+      f.flock(File::LOCK_EX | File::LOCK_NB) && drun.state(distill_dir).dig('last', 'status') == 'running'
+    end
+    puts '  (no process holds the drafting lock: that run died before it finished)' if died
+  end
+  drafts = drun.drafts(distill_dir)
+  puts "  drafts: #{drafts.empty? ? '(none)' : drafts.first(3).map { |d| d['stamp'] }.join(', ')}"
+  puts "  to adopt the newest: edit #{drafts.first['edit_path']}, then run agent_rule.rb adopt" unless drafts.empty?
   exit 0
 end
+if action == 'distill'
+  # The worker in the foreground, run by the operator: the same code path a
+  # count starts, without the count.
+  env = { 'KAIROS_PROJECT_ROOT' => Dir.pwd, 'KAIROS_DATA_DIR' => data_dir }
+  env['KAIROS_SERVER_LIB'] = ENV['KAIROS_SERVER_LIB'] if ENV['KAIROS_SERVER_LIB']
+  puts 'Drafting (this calls the distiller model and may take several minutes)...'
+  ok = system(env, RbConfig.ruby, File.expand_path('agent_distill.rb', __dir__), '--manual')
+  exit(ok ? 0 : 1)
+end
 if action == 'shadow'
   ar = KairosMcp::SkillSets::Agent::AnswerRuling
   sj = KairosMcp::SkillSets::Agent::ShadowJudge
@@ -114,14 +164,25 @@ if action == 'shadow'
   verdict_dir = lambda do |sid, anchor|
     sid.to_s.match?(/\A[\w-]+\z/) ? sj.anchor_dir(File.join(sessions, sid.to_s), anchor) : File::NULL
   end
-  sum = sj.agreement(records, verdict_dir: verdict_dir)
-  yes = sum['operator_approved']
-  no = sum['operator_did_not_approve']
-  puts "Pairs that count as evidence (your terminal answer, sealed before it): #{sum['pairs']}"
-  puts "  you approved:          #{yes['n']}; the judge also approved #{yes['judge_agreed']}"
-  puts "  you did not approve:   #{no['n']}; the judge gave the same answer #{no['judge_agreed']}, approved #{no['judge_approved']}"
-  puts "  the judge approved #{sum['judge_approved']} of #{sum['pairs']}"
-  puts "Not counted: #{sum['not_counted'].empty? ? '(none)' : sum['not_counted'].map { |k, v| "#{k} #{v}" }.join(', ')}"
+  # Counted apart for each version of what shaped the judge (distillation
+  # design v0.2 INV-K5): a new adoption, a mode edit or a new judge prompt
+  # starts a new count; earlier counts are shown, not merged.
+  by = sj.agreement_by_version(records, verdict_dir: verdict_dir)
+  total = by['versions'].sum { |v| v['summary']['pairs'] }
+  puts "Pairs that count as evidence (your terminal answer, sealed before it): #{total}, " \
+       "in #{by['versions'].size} version(s), newest first"
+  by['versions'].each_with_index do |v, i|
+    sum = v['summary']
+    key = v['version']
+    yes = sum['operator_approved']
+    no = sum['operator_did_not_approve']
+    puts "Version #{i + 1} (seals ##{v['first_seal']}..##{v['last_seal']}): judge prompt #{key['judge_prompt'].to_s[0, 12].then { |x| x.empty? ? '(before 3.92.0)' : x }}, " \
+         "reads #{key['reads'].map { |r| r.sub(/:(\h{12})\h+\z/, ':\1') }.join(' ')}"
+    puts "  you approved:          #{yes['n']}; the judge also approved #{yes['judge_agreed']}"
+    puts "  you did not approve:   #{no['n']}; the judge gave the same answer #{no['judge_agreed']}, approved #{no['judge_approved']}"
+    puts "  the judge approved #{sum['judge_approved']} of #{sum['pairs']}"
+  end
+  puts "Not counted: #{by['not_counted'].empty? ? '(none)' : by['not_counted'].map { |k, v| "#{k} #{v}" }.join(', ')}"
   exit 0
 end
 
@@ -132,7 +193,13 @@ rescue StandardError => e
 end
 
 begin
-  result = if action == 'answer'
+  result = if action == 'adopt'
+             KairosMcp::SkillSets::Agent::Adoption.interactive_adopt(
+               dir: KairosMcp::SkillSets::Agent::Session.storage_path('agent_distill'),
+               sessions_dir: KairosMcp::SkillSets::Agent::Session.storage_path('agent_sessions'),
+               stamp: stamp, tty_in: tty, tty_out: tty
+             )
+           elsif action == 'answer'
              KairosMcp::SkillSets::Agent::AnswerRuling.interactive_answer(
                session: session, gate: KairosMcp::SkillSets::Agent::AdvanceGate.new(session.guard_dir),
                tty_in: tty, tty_out: tty, reload: -> { KairosMcp::SkillSets::Agent::Session.load(session_id) }