chocomint 1.0.0

data/lib/chocomint/orchestrator.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "timeout"
+require "json_schemer"
+require_relative "errors"
+
+module Chocomint
+  # ツール実行を完全制御するオーケストレータ (DESIGN §5, §6, §9)。
+  # LLM は提案者と監査者に限定し、実行・判定・再試行・記録は Ruby が担う (DESIGN §20)。
+  class Orchestrator
+    Result = Struct.new(:status, :trace_id, :attempts, :result, :proposal, keyword_init: true)
+
+    def initialize(primary:, registry:, machine_validator:, semantic_validator:, logger:,
+                   max_retry: 10, timeout_sec: 30)
+      @primary = primary
+      @registry = registry
+      @machine_validator = machine_validator
+      @semantic_validator = semantic_validator
+      @logger = logger
+      @max_retry = max_retry
+      @timeout_sec = timeout_sec
+    end
+
+    StepResult = Struct.new(:machine_ok, :result, :error, keyword_init: true)
+
+    # マルチステップ (Planner) 用: 確定済みの 1 proposal を実行し、機械検証する。
+    # LLM への再提案は行わず、実行 + machine 検証の結果だけを返す
+    # (提案・全体達成判定・ループ制御は Planner の責務)。
+    # 提案の形状 (未知ツール / スキーマ不一致) は事前に検証し、不正なら例外を送出する。
+    # 戻り値: StepResult(machine_ok, result, error)。
+    def run_step(proposal)
+      validate_proposal_shape!(proposal)
+      result, machine_ok, error = execute_and_machine_validate(proposal)
+      result ||= { exit_code: 1, stdout: "", stderr: error.to_s, duration_ms: 0 }
+      # machine 検証は通ったが error が無い正常応答で exit_code!=0 のケースを補う。
+      error ||= result[:stderr].to_s.empty? ? nil : result[:stderr] unless machine_ok
+      StepResult.new(machine_ok: machine_ok, result: result, error: error)
+    end
+
+    # 成功時は Result(status: "PASS")。回復不能時は例外を送出する (DESIGN §14)。
+    def run(request, expectations: nil)
+      trace_id = SecureRandom.uuid
+
+      # Step 1: Tool Proposal — JSON invalid / unknown tool は FAIL。
+      # LLM 通信エラー (タイムアウト等) は一時的な障害として RETRY に乗せる。
+      proposal, propose_error = propose(request, trace_id)
+
+      attempt = 0
+      # 初回から前回までの全試行 (提案 + 失敗原因) を蓄積し、再提案時にまとめて渡す。
+      history = []
+      loop do
+        attempt += 1
+        # backoff は上限を設けて過度な待機を防ぐ (attempt 数増加に対応 / DESIGN §6)。
+        sleep([attempt - 1, 5].min) if attempt > 1
+
+        if proposal.nil?
+          # propose/repropose が LLM 通信エラーで失敗した回。ツール実行はスキップし RETRY へ。
+          result = { exit_code: 1, stdout: "", stderr: propose_error.to_s, duration_ms: 0 }
+          status = "RETRY"
+          verifier_output = nil
+          error = propose_error
+        else
+          result, machine_ok, error = execute_and_machine_validate(proposal)
+
+          if machine_ok
+            begin
+              pass, verifier_output = @semantic_validator.validate(
+                request: request, result: result, expectations: expectations,
+                trace_id: trace_id, proposal: proposal
+              )
+            rescue Chocomint::Error => e
+              # verifier の LLM 通信エラーも一時的な障害として RETRY 扱いにする。
+              pass = false
+              verifier_output = nil
+              error = "verifier request failed: #{e.message}"
+            end
+
+            if pass
+              @logger.record(trace_id: trace_id, attempt: attempt, request: request,
+                             proposal: proposal, result: result, status: "PASS",
+                             verifier_output: verifier_output)
+              return Result.new(status: "PASS", trace_id: trace_id, attempts: attempt,
+                                result: result, proposal: proposal)
+            end
+
+            status = "RETRY" # verifier=0 or invalid
+            error ||= "semantic validation failed: #{verifier_output}"
+          else
+            verifier_output = nil
+            status = "RETRY"
+            result ||= { exit_code: 1, stdout: "", stderr: error.to_s, duration_ms: 0 }
+            # tool 例外時は error が入るが、ツールが正常応答で exit_code!=0 を
+            # 返しただけの場合は error が nil のまま残るため、result のエラー内容で補う
+            # (repropose の feedback に失敗理由を確実に載せるため)。
+            error ||= result[:stderr]&.empty? == false ? result[:stderr] : "machine validation failed"
+          end
+        end
+
+        @logger.record(trace_id: trace_id, attempt: attempt, request: request,
+                       proposal: proposal || { "error" => error.to_s }, result: result,
+                       status: status, verifier_output: verifier_output)
+
+        # この試行の提案と失敗原因を履歴に残す (次の再提案の材料にするため nil でも保持する)。
+        history << { attempt: attempt, proposal: proposal, error: error }
+
+        if attempt < @max_retry
+          # 初回〜前回までの全試行を渡し、同じ失敗を繰り返さないよう再提案する (DESIGN §6)。
+          proposal, propose_error = repropose(request, history, trace_id)
+          next
+        end
+
+        @logger.record(trace_id: trace_id, attempt: attempt, request: request,
+                       proposal: proposal || { "error" => error.to_s }, result: result,
+                       status: "FAIL", verifier_output: verifier_output)
+        raise RetryLimitExceededError, "retry limit exceeded (#{@max_retry})"
+      end
+    end
+
+    private
+
+    # 戻り値: [proposal_or_nil, error_or_nil]。LLM 通信エラーは一時的な障害として
+    # nil 提案 + エラーメッセージを返し、呼び出し元で RETRY に乗せる。
+    def propose(request, trace_id)
+      proposal = @primary.propose(request, trace_id: trace_id)
+      validate_proposal_shape!(proposal)
+      [proposal, nil]
+    rescue InvalidProposalError, UnknownToolError => e
+      @logger.record(trace_id: trace_id, attempt: 0, request: request,
+                     proposal: { "error" => e.message }, result: {}, status: "FAIL")
+      raise
+    rescue Chocomint::Error => e
+      [nil, e.message]
+    end
+
+    # 初回から前回までの全試行履歴を渡して別の引数の提案を得る。
+    # 再提案自体が失敗したら直前の提案を維持して再試行する (堅牢性優先)。
+    # LLM 通信エラーのみ nil 提案を返し、次の attempt で改めて再提案を試みる。
+    def repropose(request, history, trace_id)
+      proposal = @primary.propose(request, feedback: history, trace_id: trace_id)
+      validate_proposal_shape!(proposal)
+      [proposal, nil]
+    rescue InvalidProposalError, UnknownToolError
+      [history.last[:proposal], nil]
+    rescue Chocomint::Error => e
+      [nil, e.message]
+    end
+
+    def validate_proposal_shape!(proposal)
+      tool_name = proposal["tool"]
+      args = proposal["arguments"]
+      raise InvalidProposalError, "arguments must be an object" unless args.is_a?(Hash)
+
+      tool = @registry.fetch(tool_name) # 未知なら UnknownToolError
+      schemer = JSONSchemer.schema(tool.schema)
+      return if schemer.valid?(args)
+
+      raise InvalidProposalError,
+            "arguments do not match schema for #{tool_name}: " \
+            "#{schemer.validate(args).map { |e| e['error'] }.join('; ')}"
+    end
+
+    # 戻り値: [result_or_nil, machine_ok(bool), error_or_nil]
+    # tool 例外 / timeout は RETRY 扱い (DESIGN §14)。
+    def execute_and_machine_validate(proposal)
+      tool = @registry.fetch(proposal["tool"])
+      result = Timeout.timeout(@timeout_sec) { tool.call(proposal["arguments"]) }
+      [result, @machine_validator.valid?(proposal, result), nil]
+    rescue Timeout::Error
+      [nil, false, "timeout after #{@timeout_sec}s"]
+    rescue StandardError => e
+      [nil, false, e.message]
+    end
+  end
+end

data/lib/chocomint/planner.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "errors"
+
+module Chocomint
+  # マルチステップの逐次実行オーケストレータ。
+  #
+  # 単一ツールで完結する要求だけでなく、「uv があるか確認 → python インストール →
+  # 依存追加 → 仮想環境作成」のように複数のツールを順に実行して達成する要求に対応する。
+  #
+  # 各ステップで主 LLM に「次に実行すべき 1 ツール」を提案させ (propose_step)、
+  # Orchestrator#run_step で実行・機械検証し、副 LLM (verifier) が
+  # 「要求全体が達成されたか」を判定する。達成なら完了、未達成なら次ステップへ進む。
+  # LLM は提案者・監査者に限定し、実行・判定・ループ制御・記録は Ruby が担う (DESIGN §20)。
+  class Planner
+    # steps: 実行した各ステップ [{ tool:, arguments:, result:, status: }, ...]
+    # message: モデルがユーザーへ伝える最終メッセージ (finish 時のみ / 任意)。
+    # incomplete: verifier 未達成のまま成果を返した (要求を満たしきれていない可能性がある) か。
+    #   true のとき UI は message を「注記」として控えめに扱う (通常の要約とは区別する)。
+    Result = Struct.new(:status, :trace_id, :steps, :attempts, :message, :incomplete,
+                        keyword_init: true)
+
+    # max_steps: 実行を許すステップ数の上限 (暴走防止)。max_retry を流用する。
+    # step_retry: 1 ステップが machine 検証で失敗したとき、引数を変えて再提案する回数。
+    def initialize(primary:, orchestrator:, verifier:, logger:,
+                   max_steps: 10, step_retry: 3)
+      @primary = primary
+      @orchestrator = orchestrator
+      @verifier = verifier
+      @logger = logger
+      @max_steps = max_steps
+      @step_retry = step_retry
+    end
+
+    # 要求を達成するまでツールを 1 つずつ実行する。
+    # 成功時は Result(status: "PASS")。max_steps 到達で達成できなければ
+    # RetryLimitExceededError を送出する (それまでの成功ステップは監査ログに残る)。
+    #
+    # on_event: 進捗を逐次通知するコールバック (任意)。UI のリアルタイム表示に使う。
+    #   呼ばれるイベント (いずれも Hash):
+    #     { type: "step_start", step: n, tool:, label:, target: } … ツール実行の直前
+    #     { type: "step_done",  step: n, tool:, label:, target:, status:, exit_code:, output: } … 実行後
+    #   コールバック内の例外は握りつぶす (通知失敗で実行本体を止めないため)。
+    def run(request, expectations: nil, on_event: nil)
+      trace_id = SecureRandom.uuid
+      done_steps = []
+      total_attempts = 0
+
+      @max_steps.times do |i|
+        step_no = i + 1
+        proposal, error = propose_and_execute(request, done_steps, trace_id, step_no, on_event)
+        total_attempts += 1
+
+        if proposal.nil?
+          # ステップ内リトライを使い切っても実行できなかった。ここで打ち切る。
+          @logger.record(trace_id: trace_id, attempt: step_no, request: request,
+                         proposal: { "error" => error.to_s }, result: {}, status: "FAIL")
+          raise RetryLimitExceededError,
+                "step #{step_no} failed after #{@step_retry} retries: #{error}"
+        end
+
+        tool = proposal["tool"]
+        result = proposal.delete(:__result)
+
+        # finish 提案はループ終了の合図 (実行はしない)。
+        if tool == LLM::PrimaryClient::FINISH_TOOL
+          return finish(request, done_steps, trace_id, step_no, total_attempts,
+                        expectations, message: finish_message(proposal))
+        end
+
+        step = { tool: tool, arguments: proposal["arguments"], result: result, status: "PASS" }
+        done_steps << step
+        @logger.record(trace_id: trace_id, attempt: step_no, request: request,
+                       proposal: proposal, result: result, status: "STEP")
+
+        # 全体達成判定。達成なら完了。未達成なら次ステップへ。
+        pass, verifier_output = verify_overall(request, done_steps, expectations, trace_id)
+        next unless pass
+
+        @logger.record(trace_id: trace_id, attempt: step_no, request: request,
+                       proposal: proposal, result: result, status: "PASS",
+                       verifier_output: verifier_output)
+        return Result.new(status: "PASS", trace_id: trace_id, steps: done_steps,
+                          attempts: total_attempts)
+      end
+
+      # max_steps 到達。要求を達成しきれなかった。
+      @logger.record(trace_id: trace_id, attempt: @max_steps, request: request,
+                     proposal: { "error" => "max steps reached" }, result: {}, status: "FAIL")
+      raise RetryLimitExceededError, "step limit exceeded (#{@max_steps})"
+    end
+
+    private
+
+    # 次ステップを提案させ、machine 検証を通るまで最大 step_retry 回まで引数を変えて再提案する。
+    # 成功時は proposal に実行結果を :__result で埋めて返す。
+    # 戻り値: [proposal_or_nil, error_or_nil]。
+    def propose_and_execute(request, done_steps, trace_id, step_no, on_event = nil)
+      last_error = nil
+      @step_retry.times do
+        proposal = safe_propose(request, done_steps, trace_id)
+        return [nil, "proposal failed: #{@propose_error}"] if proposal.nil?
+
+        # finish はそのまま返す (実行不要)。
+        return [proposal, nil] if proposal["tool"] == LLM::PrimaryClient::FINISH_TOOL
+
+        # ツール名が確定したので、実行の直前に UI へ「実行中」を通知する。
+        emit(on_event, step_start_event(step_no, proposal))
+        step = @orchestrator.run_step(proposal)
+        if step.machine_ok
+          proposal[:__result] = step.result
+          emit(on_event, step_done_event(step_no, proposal, step.result, "PASS"))
+          return [proposal, nil]
+        end
+
+        last_error = step.error
+        emit(on_event, step_done_event(step_no, proposal, step.result, "FAILED"))
+        # 失敗ステップも監査ログに残す (RETRY)。次の周回で別の引数を提案させる。
+        @logger.record(trace_id: trace_id, attempt: step_no, request: request,
+                       proposal: proposal, result: step.result, status: "RETRY")
+        done_steps = done_steps + [failed_hint(proposal, step)]
+      end
+      [nil, last_error]
+    rescue InvalidProposalError, UnknownToolError => e
+      # 提案の形状が不正。ステップとして回復不能なのでそのまま伝播させる。
+      @logger.record(trace_id: trace_id, attempt: step_no, request: request,
+                     proposal: { "error" => e.message }, result: {}, status: "FAIL")
+      raise
+    end
+
+    # LLM 通信エラーは一時的な障害として nil を返し、呼び出し元でリトライさせる。
+    def safe_propose(request, done_steps, trace_id)
+      @propose_error = nil
+      @primary.propose_step(request, done_steps, trace_id: trace_id)
+    rescue InvalidProposalError, UnknownToolError
+      raise
+    rescue Chocomint::Error => e
+      @propose_error = e.message
+      nil
+    end
+
+    # 失敗したステップを、次の提案時に「避けるべき試み」として履歴へ添えるためのヒント。
+    def failed_hint(proposal, step)
+      { tool: proposal["tool"], arguments: proposal["arguments"],
+        result: step.result, status: "FAILED", error: step.error }
+    end
+
+    # 進捗コールバックを安全に呼ぶ (通知失敗で実行本体を止めない)。
+    def emit(on_event, event)
+      return unless on_event
+
+      on_event.call(event)
+    rescue StandardError
+      nil
+    end
+
+    # UI 表示用の整形 (label/target) は呼び出し側 (handler) の責務なので、
+    # ここでは生の tool 名・引数・結果だけをイベントに載せる。
+    def step_start_event(step_no, proposal)
+      { type: "step_start", step: step_no,
+        tool: proposal["tool"], arguments: proposal["arguments"] }
+    end
+
+    def step_done_event(step_no, proposal, result, status)
+      { type: "step_done", step: step_no,
+        tool: proposal["tool"], arguments: proposal["arguments"],
+        result: result, status: status }
+    end
+
+    # verifier 無効時は常に達成扱い (単一ステップは 1 回で完了する)。
+    # LLM 通信エラーは未達成 (次ステップ継続) として扱い、ループを止めない。
+    def verify_overall(request, done_steps, expectations, trace_id)
+      return [true, nil] if @verifier.nil?
+
+      output = @verifier.verify_overall(
+        request: request, done_steps: done_steps,
+        expectations: expectations, trace_id: trace_id
+      )
+      [output == "1", output]
+    rescue Chocomint::Error => e
+      [false, "verifier request failed: #{e.message}"]
+    end
+
+    # 要求を完全には満たせていない可能性があるときにメッセージへ添える注記。
+    INCOMPLETE_NOTE = "要求を完全には満たせていない可能性があります。" \
+                      "結果を確認し、必要なら続けて指示してください。"
+
+    # finish 提案を受けた場合の最終判定。verifier が達成を確認できれば PASS。
+    #
+    # ツールを一度も実行せずに message 付きで finish した場合は、モデルが
+    # ツール不要で答えた/情報不足を聞き返したケースとみなし、verifier をかけずに
+    # そのメッセージを返して正常終了する (聞き返しを失敗にしないため)。
+    #
+    # verifier が未達成と判断した場合でも、ステップを 1 つ以上実行済みなら、それまでの
+    # 成果を PASS として返す (未完了の注記を添える)。小型 verifier の誤判定で成果ごと
+    # 捨てて生エラーを出すより、実行済みの結果を見せて続きを促す方が有用なため。
+    # 何も実行していない (done_steps 空) 状態での未達成 finish は、誤った完了宣言として失敗にする。
+    def finish(request, done_steps, trace_id, step_no, total_attempts, expectations, message: nil)
+      if done_steps.empty? && !message.to_s.empty?
+        @logger.record(trace_id: trace_id, attempt: step_no, request: request,
+                       proposal: { "tool" => LLM::PrimaryClient::FINISH_TOOL, "message" => message },
+                       result: {}, status: "PASS")
+        return Result.new(status: "PASS", trace_id: trace_id, steps: done_steps,
+                          attempts: total_attempts, message: message)
+      end
+
+      pass, verifier_output = verify_overall(request, done_steps, expectations, trace_id)
+
+      # 未達成だがステップは実行済み: 成果を捨てず PASS で返す (incomplete フラグを立て、
+      # message は未完了の注記のみにする。実行内容の要約は呼び出し側が別途生成する)。
+      if !pass && !done_steps.empty?
+        @logger.record(trace_id: trace_id, attempt: step_no, request: request,
+                       proposal: { "tool" => LLM::PrimaryClient::FINISH_TOOL }, result: {},
+                       status: "PASS", verifier_output: verifier_output)
+        return Result.new(status: "PASS", trace_id: trace_id, steps: done_steps,
+                          attempts: total_attempts, message: INCOMPLETE_NOTE, incomplete: true)
+      end
+
+      status = pass ? "PASS" : "FAIL"
+      @logger.record(trace_id: trace_id, attempt: step_no, request: request,
+                     proposal: { "tool" => LLM::PrimaryClient::FINISH_TOOL }, result: {},
+                     status: status, verifier_output: verifier_output)
+      unless pass
+        raise RetryLimitExceededError,
+              "LLM declared finish but requirement not satisfied: #{verifier_output}"
+      end
+      Result.new(status: "PASS", trace_id: trace_id, steps: done_steps,
+                 attempts: total_attempts, message: message)
+    end
+
+    # finish 提案の arguments からユーザー向けメッセージを取り出す (無ければ nil)。
+    def finish_message(proposal)
+      args = proposal["arguments"]
+      return nil unless args.is_a?(Hash)
+
+      msg = args["message"] || args["reason"]
+      msg.to_s.strip.empty? ? nil : msg.to_s.strip
+    end
+  end
+end

data/lib/chocomint/security/path_guard.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Chocomint
+  module Security
+    # 許可ディレクトリ配下のみアクセスを許し、パストラバーサルを防ぐ (DESIGN §13)。
+    class PathGuard
+      attr_reader :base_dir, :allowed_roots
+
+      def initialize(allowed_dirs, base_dir: Dir.pwd)
+        @base_dir = File.expand_path(base_dir)
+        @allowed_roots = Array(allowed_dirs).map do |d|
+          File.expand_path(d, @base_dir)
+        end
+      end
+
+      # 例外を投げずに許可判定だけ行う。
+      def allowed?(path)
+        resolve(path)
+        true
+      rescue PathAccessError
+        false
+      end
+
+      # 検証済み絶対パスを返す。許可外なら PathAccessError。
+      def resolve(path)
+        raise PathAccessError, "path is required" if path.nil? || path.to_s.empty?
+
+        abs = File.expand_path(path.to_s, @base_dir)
+        unless @allowed_roots.any? { |root| under?(root, abs) }
+          raise PathAccessError, "access denied: #{path} is outside allowed directories"
+        end
+
+        abs
+      end
+
+      # run_command / shell の引数トークン列を検査する。ファイル系ツールと違い外部
+      # プロセスは cwd (=base_dir) 配下で好き放題できてしまうため、引数に現れる
+      # 「パスらしいトークン」が allowed_roots 内に収まるかだけ事前に確認する。
+      # 過剰検知を避けるため、パス判定はスラッシュ/バックスラッシュを含むか ".." を
+      # 含むトークンに限る (venv / pandas / init のような非パス引数は素通しする)。
+      # 許可外を指すトークンがあれば PathAccessError。
+      def validate_args!(args)
+        Array(args).each do |token|
+          value = extract_path_value(token.to_s)
+          next unless value && path_like?(value)
+
+          resolve(value) # 許可外なら PathAccessError を送出
+        end
+        true
+      end
+
+      private
+
+      # "--directory=workspace/x" のような "フラグ=値" は値側だけを取り出す。
+      # 先頭が "-" のみのフラグ (値を含まない) は nil を返しパス扱いしない。
+      def extract_path_value(token)
+        if token.start_with?("-")
+          idx = token.index("=")
+          idx ? token[(idx + 1)..] : nil
+        else
+          token
+        end
+      end
+
+      # スラッシュ/バックスラッシュを含む、または ".." を含むものだけをパス候補とみなす。
+      def path_like?(token)
+        return false if token.empty?
+
+        token.include?("/") || token.include?("\\") ||
+          token.split(%r{[/\\]}).include?("..")
+      end
+
+      # abs が root と一致、または root 配下かを判定 (prefix 攻撃を避ける)。
+      def under?(root, abs)
+        return true if abs == root
+
+        prefix = root.end_with?(File::SEPARATOR) ? root : root + File::SEPARATOR
+        abs.start_with?(prefix)
+      end
+    end
+  end
+end