kairos-chain 3.89.0 → 3.91.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 109c03e66d55828499533b9d00945390f97cfd8aa56376aa898c099a30218316
-  data.tar.gz: 3013372fe35ae2bf4e3e5a4267fed64197e7480da32f2030664eb61766724f44
+  metadata.gz: 8edb08c26be7f068db03e377e1f9d48ba67135b233dfa16f0fab9e7126364bca
+  data.tar.gz: 81557a33e8214065bf3e692948b58e3655e0758f5b95e13ae19c9bcc67c4cf17
 SHA512:
-  metadata.gz: 824d9d93d7e2c22a991e116a2f8c66acf8d54ecb2469a541c2f51a0ae982b0018d2650f88931daa5cf6da2091bba5ed470e13334c7b341d09fdfa2a7f48c01f8
-  data.tar.gz: bcc18d3c8123b54db6b934fc475f8517a7cd3dc2562a34d213c37140f08b45218d461c3685216f6577e9683de111f7ec70a07f9da27e5bfe947d0e740caffc5f
+  metadata.gz: a6fbd7b1e9a1a347f941d292c6b0b55c8801b8ca609503281721d175a7567f27e2b20791ded6b2404eefbc3c6d7d8e84b16f3136fa0faffdad39d3bed574b044
+  data.tar.gz: fcff23454d07a3720ddb982a421137b292e9844228276e445181062ec64ac06025bf4cc4d0afe6c5be4202d889f1b8ddacf10eaa3859cc87ee2d998e627789d4

data/CHANGELOG.md

@@ -4,6 +4,102 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.91.0] - 2026-10-07
+
+### Added — agent: a shadow judge beside the operator (approval delegation, phase 1)
+
+At the points the new delegation table covers, a fresh model answers the
+operator's question beside the operator, and the two answers are compared
+later. **In this phase the judge's answer changes nothing**: every point still
+waits for you.
+
+- **The delegation table** (`lib/agent/delegation_table.yml`) names two
+  points: plan approval in a manual session (`plan_proposed`) and the
+  scheduled checkpoint (`cycle_checkpoint`). Every row is `shadow`; the loader
+  refuses a table with any other mode or with an `mlr` approver. Like the
+  act-route table it is in force only by your terminal ruling, which also pins
+  the instruction mode the judge reads; editing that mode takes the table out
+  of force until you rule again:
+
+      ruby .kairos/skillsets/agent/bin/agent_rule.rb activate --table delegation
+
+  With no ruling, behaviour is as before.
+- **Which points are judged**: only when the act route classifies every step of
+  the plan, no step is marked for a person, nothing touches L0, and the goal is
+  unchanged since the run started. Rows and precedents are chosen only by
+  signals the driver observes from the plan's structure — never by the plan's
+  summary wording or its own risk labels.
+- **The judge** is a separate process (`bin/agent_shadow_judge.rb`) started
+  once the session has stopped at the point; nothing waits for it. It asks
+  `claude-opus-5-5` at effort `xhigh` through `llm_call` (`claude -p`,
+  sandboxed, no fallback provider) with the plan, the driver's signals, the
+  goal, your instruction mode and up to five of your earlier terminal answers
+  at the same kind of stop. Anything but a clear answer from that model counts
+  as "hand back to the operator".
+- **Sealed, then shown**: the verdict goes on the chain as a salted commitment
+  (`agent_shadow_seal`) and is shown only after your answer at that point has
+  committed — in that `agent_step` response and in `agent_status` under
+  `shadow`. Before then `agent_status` says only `judging`, `sealed` or
+  `failed`. The verdict file sits in the session directory; reading it before
+  you answer defeats the comparison.
+- **Counting**: `agent_rule.rb shadow` counts agreement only for answers you
+  typed at the terminal whose seal came first, approve and non-approve apart.
+- Each judged point is one Opus call at `xhigh`.
+
+### Changed — agent: a run with a failed act is not the scheduled checkpoint
+
+An autonomous run now stops as `cycle_checkpoint` only when every act of the
+run succeeded — including an act resumed after a risk pause. A run in which an
+act failed without an act error (a step failed or was denied, the guard failed
+it) stops as `act_failed`, as a failed manual-mode act already did.
+
+### Fixed — agent: a torn read of the chain no longer empties the act-route table
+
+The table loaders retry a read that overlaps a chain append, as the answer
+reader already did.
+
+## [3.90.0] - 2026-10-07
+
+### Added — agent: every answer is a ruling on the chain, and an answer typed at a terminal binds
+
+Until now the gate log kept which answer advanced a session, but not who gave
+it, why, or what it was given to. **Every answer that advances an agent session
+is now recorded on the chain as a ruling** (`agent_answer`) — through
+`agent_step` (approve, revise, skip, stop, adjudicate) and `agent_stop` alike.
+
+- **What a ruling holds**: the point it answered (state, cycle, and why the
+  session was waiting), the plan's SHA-256 and the driver's own signals when a
+  plan was the subject, the act-route table in force, the decision, and whether
+  it was attested. A replayed retry writes none. A ruling that fails to record
+  never blocks the answer; the response says so under `ruling`. Reasons
+  (`rationale`, new optional argument) and revise feedback stay off the chain;
+  the ruling carries their SHA-256.
+- **Answer as yourself, at a terminal**:
+
+      ruby .kairos/skillsets/agent/bin/agent_rule.rb answer SESSION_ID
+
+  It shows why the session stopped and the whole plan (every argument, escaped,
+  and the file it is kept in), asks for your answer, an optional reason and a
+  nonce, and records the answer bound to that point and that plan. The answer
+  then sent through `agent_step` there must be the same one, or it is refused
+  (`answer_refused`); **a stop always goes through**. After a revise at the
+  terminal, send `revise` without feedback and your text is used. Pass
+  `--project-dir` when the MCP server runs in another directory than the
+  project holding its data dir. An answer sent only through MCP is recorded as
+  the caller's, unattested.
+- **Every waiting session says why it stopped** (`stop` in every response and in
+  `agent_status`). `cycle_checkpoint` means only the scheduled end-of-cycle
+  stop (Gate 8, or a manual act that succeeded and left nothing over); failed
+  acts, set-aside steps, guard halts, adjudications, risk pauses and the rest
+  name themselves.
+- **While the chain cannot be read, every answer but a stop is refused**,
+  because whether you answered at the terminal cannot be checked. On chain
+  stores other than the file ledger (sqlite, postgresql) the agent can only be
+  stopped.
+
+No action is needed after upgrading. Approval delegation (the shadow judge) is
+not part of this release; do not run the agent unattended.
+
 ## [3.89.0] - 2026-10-07
 
 ### Security — agent: the act route runs from an allow-list

data/lib/kairos_mcp/version.rb

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

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

@@ -1,17 +1,29 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 #
-# The operator's terminal ruling on the agent's act-route allow-list
-# (design v0.3, INV-A2 / INV-D8).
+# The operator's terminal rulings for the agent (design v0.3, INV-A2 / INV-D8):
+# the act-route allow-list, the delegation table, and answers at a stopped
+# session.
 #
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb activate   # rule the current table into force
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb withdraw   # take it out of force
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb status     # show what is in force (records nothing)
+#   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)
 #
-# Options: --data-dir DIR   the instance data dir whose chain is written
-#                           (default: the .kairos this script is installed in)
+# Options: --table NAME       activate / withdraw: act_classification (default)
+#                             or delegation
+#          --data-dir DIR     the instance data dir whose chain is written
+#                             (default: the .kairos this script is installed in)
+#          --project-dir DIR  answer / shadow: the directory the MCP server runs
+#                             in, whose .kairos/storage holds its agent sessions
+#                             (default: the directory holding the data dir).
+#                             Needed when the server runs with --data-dir
+#                             pointing at another project's .kairos.
 #
-# activate and withdraw read a nonce typed back at /dev/tty and refuse to run
+# activate, withdraw and answer 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
@@ -21,8 +33,15 @@
 
 require 'json'
 
-action = ARGV.find { |a| %w[activate withdraw status].include?(a) }
-abort 'usage: agent_rule.rb activate|withdraw|status [--data-dir DIR]' unless action
+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
+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?('-') }
+
+tidx = ARGV.index('--table')
+table = tidx ? ARGV[tidx + 1].to_s : 'act_classification'
+abort "--table must be act_classification or delegation, not #{table.inspect}" unless %w[act_classification delegation].include?(table)
 
 idx = ARGV.index('--data-dir')
 data_dir = idx ? File.expand_path(ARGV[idx + 1].to_s) : File.expand_path('../../..', __dir__)
@@ -41,10 +60,36 @@ lib = File.expand_path('../lib', __dir__)
 require File.join(lib, 'agent', 'admission')
 require File.join(lib, 'agent', 'mandate_adapter')
 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')
 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)
+  require 'kairos_mcp/invocation_context'
+  require File.join(lib, 'agent', 'session')
+  require File.join(lib, 'agent', 'advance_gate')
+  # The server keeps agent sessions under <its working directory>/.kairos/storage
+  # (Session.storage_path without Autonomos loaded), and its chain under its
+  # 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?('-') }
+  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)
+  puts "Sessions from: #{project_dir}"
+  if action == 'answer'
+    session = KairosMcp::SkillSets::Agent::Session.load(session_id)
+    unless session
+      abort "no agent session #{session_id} under #{File.join(Dir.pwd, '.kairos', 'storage', 'agent_sessions')} " \
+            '(if the MCP server runs in another directory, pass --project-dir)'
+    end
+  end
+end
 if action == 'status'
   eff = ac.load_effective(path: path)
   puts "Table #{ac::TABLE_ID}: #{eff['status']}"
@@ -52,6 +97,31 @@ if action == 'status'
   puts "  ruled sha256: #{eff['ruled_sha256'] || '(none)'}"
   puts "  detail: #{eff['detail']}" if eff['detail']
   puts "  tools in force: #{eff['tools'].keys.sort.join(', ')}" unless eff['tools'].empty?
+  deff = dl.load_effective
+  puts "Table #{dl::TABLE_ID}: #{deff['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']})" }
+  exit 0
+end
+if action == 'shadow'
+  ar = KairosMcp::SkillSets::Agent::AnswerRuling
+  sj = KairosMcp::SkillSets::Agent::ShadowJudge
+  records, error = ar.chain_records
+  abort "The chain could not be read (#{error}); nothing to count." if error
+  sessions = File.expand_path(File.join('.kairos', 'storage', 'agent_sessions'))
+  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(', ')}"
   exit 0
 end
 
@@ -62,7 +132,16 @@ rescue StandardError => e
 end
 
 begin
-  result = ac.interactive_rule(action: action, tty_in: tty, tty_out: tty, path: path)
+  result = if 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) }
+             )
+           elsif table == 'delegation'
+             dl.interactive_rule(action: action, tty_in: tty, tty_out: tty)
+           else
+             ac.interactive_rule(action: action, tty_in: tty, tty_out: tty, path: path)
+           end
 ensure
   tty.close
 end

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# The shadow judge's process (design v0.3, INV-D6 / INV-D7). Started detached
+# by the driver after an advance commits, once per anchor, with the packet the
+# driver wrote. It reads the files the packet pins, asks a fresh model the
+# operator's question, writes the verdict beside the packet and appends a
+# salted commitment to it on the chain.
+#
+# It loads no agent tool and never opens the session's advance lock: nothing
+# waits for it, and nothing it does can reach the operator's answer.
+#
+# The model is reached through llm_call (design v0.3 §4), loaded here as a
+# tool object rather than through a registry: provider claude_code (claude -p)
+# with sandbox_mode, the requested model and effort. llm_call falls back to
+# another provider only from a provider other than claude_code, so the judge
+# has none. Its timeout is llm_client's configured one (600 s as shipped).
+#
+# argv: <packet_path>
+# env:  KAIROS_SERVER_LIB  lib dir to load kairos_mcp from
+#       KAIROS_DATA_DIR    the server's data dir (the chain written)
+#       KAIROS_PROJECT_ROOT the server's working directory
+
+require 'json'
+
+packet_path = ARGV[0] or abort 'usage: agent_shadow_judge.rb <packet_path>'
+
+begin
+  Process.setsid
+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']
+  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__)
+  require File.join(lib, 'agent', 'answer_ruling')
+  require File.join(lib, 'agent', 'delegation')
+  require File.join(lib, 'agent', 'shadow_judge')
+  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
+  dir = File.dirname(packet_path)
+  File.write(File.join(dir, 'error.json'),
+             JSON.generate({ 'sealed' => false, 'error' => "bootstrap: #{e.class}: #{e.message[0, 200]}" }))
+  exit 1
+end
+
+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
+
+result = KairosMcp::SkillSets::Agent::ShadowJudge.judge_and_seal(
+  packet_path, llm: llm, chain: KairosMcp::KairosChain::Chain.new
+)
+warn JSON.generate(result)
+exit(result['sealed'] ? 0 : 1)

data/templates/skillsets/agent/lib/agent/act_classification.rb

@@ -92,16 +92,30 @@ module KairosMcp
         end
 
         # [rulings, nil] from the instance chain, or [[], reason] when the
-        # chain cannot be read (which empties the table).
+        # chain cannot be read (which empties the table). The ledger is
+        # rewritten in place on every append, and the shadow judge appends
+        # from its own process at any moment, so a read is retried before a
+        # torn one empties the table (as AnswerRuling.chain_records).
+        READ_ATTEMPTS = 3
+
         def chain_rulings
           return ActClassification.rulings_source.call if ActClassification.rulings_source
 
           require 'kairos_mcp/kairos_chain/chain'
-          chain = ::KairosMcp::KairosChain::Chain.new
-          state = chain.load_state
-          return [[], "chain #{state}"] unless %i[readable absent].include?(state)
-
-          [rulings_from_blocks(chain.chain), nil]
+          reason = nil
+          READ_ATTEMPTS.times do |i|
+            sleep(0.05 * i) if i.positive?
+            begin
+              chain = ::KairosMcp::KairosChain::Chain.new
+              state = chain.load_state
+              return [rulings_from_blocks(chain.chain), nil] if %i[readable absent].include?(state)
+
+              reason = "chain #{state}"
+            rescue StandardError => e
+              reason = "chain unreadable: #{e.class}: #{e.message[0, 120]}"
+            end
+          end
+          [[], reason]
         rescue StandardError, ScriptError => e
           [[], "chain unreadable: #{e.class}: #{e.message[0, 120]}"]
         end