chocomint 1.0.0

data/lib/chocomint/llm/primary_client.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../errors"
+
+module Chocomint
+  module LLM
+    # 主 LLM にツール提案をさせる (DESIGN §5 Step1)。
+    # tool_use ブロックを優先し、無ければテキストから JSON を抽出する
+    # (LLM 出力形式に依存しない堅牢性: DESIGN Goals)。
+    class PrimaryClient
+      # 実行環境 (現在日時・OS・シェル) の説明。ローカルモデルが「今日の日付」や
+      # 「どの OS 上で動いているか」を誤解しないよう、システムプロンプトに毎回埋め込む。
+      # シェルは PowerShell を優先させる (Windows ネイティブ環境のため)。
+      def self.environment_prompt
+        <<~ENV.strip
+          実行環境:
+          - 現在日時: #{Time.now.strftime('%Y-%m-%d %H:%M:%S %Z')}
+          - OS: #{host_os_description}
+          - シェル: PowerShell (pwsh) を優先して使うこと。
+          コマンド実行が必要な場合は、原則として powershell ツール (または run_command) を使い、
+          PowerShell の構文で書いてください。bash 固有の構文は避けてください。
+        ENV
+      end
+
+      # RbConfig の host_os を人間可読な OS 名に整える。
+      def self.host_os_description
+        host = RbConfig::CONFIG["host_os"]
+        case host
+        when /mswin|mingw|cygwin/ then "Windows (#{host})"
+        when /darwin/ then "macOS (#{host})"
+        when /linux/ then "Linux (#{host})"
+        else host.to_s
+        end
+      end
+
+      # 共通の作業ルール (パス・workspace の扱い)。両プロンプトで共有する。
+      WORKSPACE_RULES = <<~PROMPT.strip
+        パスを指定するツールでは、必ず作業ディレクトリからの相対パス (例: workspace/foo.txt) を
+        使ってください。/workspace や /home/user/workspace のような絶対パスは許可されません。
+        run_command / bash / powershell の作業ディレクトリはプロジェクトルートです。
+        成果物は必ず workspace/ 配下に作ってください。uv など出力先ディレクトリを取るコマンドは
+        必ず --directory workspace/... のように workspace 配下を明示してください
+        (例: run_command uv init --directory workspace/myproj)。
+        最新情報や外部ドキュメントの参照が必要な場合は fetch_url ツールを使ってください。
+      PROMPT
+
+      def self.system_prompt
+        <<~PROMPT
+          あなたはツール実行を提案するアシスタントです。
+          ユーザー要求を満たすために呼び出すべきツールを 1 つだけ選び、
+          その引数を決めてください。ツールを使って応答してください。
+
+          #{environment_prompt}
+
+          #{WORKSPACE_RULES}
+        PROMPT
+      end
+
+      # マルチステップの逐次実行を促すシステムプロンプト。
+      # 1 回の応答で「次に実行すべき 1 ツール」だけを選ばせ、
+      # やることが残っていなければ finish ツールで完了を宣言させる。
+      def self.step_system_prompt
+        <<~PROMPT
+          あなたはユーザー要求を達成するために、ツールを 1 つずつ順番に実行していくアシスタントです。
+          これまでに完了したステップの一覧が与えられます。それを踏まえ、
+          「次に実行すべきツールを 1 つだけ」選び、その引数を決めてください。
+
+          ユーザー要求がすべて満たされ、もう実行すべきことが残っていない場合は、
+          finish ツールを呼び出して完了を宣言してください (それ以外のツールは呼ばないこと)。
+          まだ残作業がある場合は finish を呼ばず、次に必要なツールを 1 つだけ呼んでください。
+
+          #{environment_prompt}
+
+          #{WORKSPACE_RULES}
+        PROMPT
+      end
+
+      # 完了宣言用の疑似ツール。実際には実行されず、Planner がループ終了の合図として使う。
+      FINISH_TOOL = "finish"
+      FINISH_TOOL_DEFINITION = {
+        "name" => FINISH_TOOL,
+        "description" => "ユーザー要求がすべて達成され、もう実行すべきツールが残っていないときに呼ぶ。",
+        "input_schema" => {
+          "type" => "object",
+          "properties" => {
+            "reason" => { "type" => "string", "description" => "完了と判断した理由 (任意)" },
+            "message" => { "type" => "string", "description" => "ユーザーへ伝える最終メッセージ (任意)" }
+          }
+        }
+      }.freeze
+
+      def initialize(base_client:, tool_definitions:)
+        @client = base_client
+        @tool_definitions = tool_definitions
+      end
+
+      # マルチステップ用: これまで完了したステップを踏まえ、次に実行すべき 1 ツールを提案する。
+      # 完了していれば tool="finish" を返す (Planner がループ終了に使う)。
+      # 戻り値: { "tool" => name, "arguments" => Hash }
+      # done_steps: [{ tool:, arguments:, result: }, ...] 形式の完了済みステップ列。
+      def propose_step(request, done_steps = [], trace_id: nil)
+        response = @client.create_message(
+          system: self.class.step_system_prompt,
+          tools: @tool_definitions + [FINISH_TOOL_DEFINITION],
+          messages: build_step_messages(request, done_steps),
+          trace_id: trace_id
+        )
+
+        # ツール提案があればそれを優先。無ければモデルの自然文応答を「finish + メッセージ」
+        # として扱う。天気の問い合わせで場所を聞き返すなど、モデルがツールではなく
+        # テキストで応答するのは正当なので、これを失敗にせずユーザーへ返す (聞き返し対応)。
+        # ここでは JSON 抽出の失敗を致命エラーにしない (strict: false)。自然文に壊れた
+        # JSON 断片が混じっていても、聞き返し (from_text_reply) にフォールバックさせる。
+        from_tool_use(response) || from_text(response, strict: false) ||
+          from_text_reply(response) ||
+          raise(InvalidProposalError, "step proposal contains no valid tool call")
+      end
+
+      # 戻り値: { "tool" => name, "arguments" => Hash }
+      # feedback: 初回〜前回までの全試行履歴 (再提案時に引数を変えさせるため / DESIGN §6)。
+      #   [{ attempt:, proposal:, error: }, ...] 形式。旧来の単一 Hash も許容する。
+      def propose(request, feedback: nil, trace_id: nil)
+        response = @client.create_message(
+          system: self.class.system_prompt,
+          tools: @tool_definitions,
+          messages: build_messages(request, feedback),
+          trace_id: trace_id
+        )
+
+        from_tool_use(response) || from_text(response) ||
+          raise(InvalidProposalError, "proposal contains no valid tool call")
+      end
+
+      private
+
+      # マルチステップの提案メッセージ。要求と、これまで完了したステップの一覧を渡す。
+      # 完了ステップが無ければ最初のステップとして要求だけを渡す。
+      def build_step_messages(request, done_steps)
+        messages = [{ "role" => "user", "content" => request.to_s }]
+        steps = Array(done_steps)
+        return messages if steps.empty?
+
+        lines = steps.each_with_index.map do |s, i|
+          tool = s[:tool] || s["tool"]
+          args = s[:arguments] || s["arguments"]
+          result = s[:result] || s["result"]
+          "  ステップ#{i + 1}: ツール=#{tool} 引数=#{JSON.generate(args)} " \
+            "結果=#{summarize_result(result)}"
+        end
+        messages << {
+          "role" => "user",
+          "content" => <<~MSG.strip
+            これまでに以下のステップが完了しています。
+            #{lines.join("\n")}
+            上記を踏まえ、ユーザー要求を達成するために次に実行すべきツールを 1 つだけ選んでください。
+            すでにすべて達成されている場合は finish ツールを呼んでください。
+            同じ引数のツールを無意味に繰り返さないでください。
+          MSG
+        }
+        messages
+      end
+
+      # ステップ結果を提案プロンプト向けに 1 行へ要約する (exit_code と stdout 冒頭)。
+      RESULT_SUMMARY_LIMIT = 200
+
+      def summarize_result(result)
+        return "(なし)" unless result.is_a?(Hash)
+
+        code = result[:exit_code] || result["exit_code"]
+        out = (result[:stdout] || result["stdout"]).to_s.strip
+        err = (result[:stderr] || result["stderr"]).to_s.strip
+        parts = ["exit_code=#{code}"]
+        parts << "stdout=#{truncate(out)}" unless out.empty?
+        parts << "stderr=#{truncate(err)}" unless err.empty?
+        parts.join(" ")
+      end
+
+      def truncate(text)
+        text.length > RESULT_SUMMARY_LIMIT ? "#{text[0, RESULT_SUMMARY_LIMIT]}…" : text
+      end
+
+      # 再提案時は初回から前回までの全試行 (提案とエラー) を添え、別の引数を試すよう促す。
+      def build_messages(request, feedback)
+        messages = [{ "role" => "user", "content" => request.to_s }]
+        history = normalize_history(feedback)
+        return messages if history.empty?
+
+        lines = history.map do |h|
+          prev = h[:proposal]
+          "  試行#{h[:attempt]}: 提案=#{prev ? JSON.generate(prev) : '(なし)'} / 失敗=#{h[:error]}"
+        end
+        hints = failure_hints(history)
+        messages << {
+          "role" => "user",
+          "content" => <<~MSG.strip
+            これまでの提案はすべて失敗しました。別の引数で再試行してください。
+            #{lines.join("\n")}
+            上記のいずれとも同じ引数を繰り返さず、パラメータを変えて提案してください。
+            #{hints}
+          MSG
+        }
+        messages
+      end
+
+      # 直近の失敗理由から、繰り返されがちな誤りに対する具体的な修正ヒントを付加する
+      # (同じ種類の失敗を LLM が学習せず何度も繰り返すのを防ぐ / DESIGN §6)。
+      FAILURE_HINTS = {
+        /access denied.*outside allowed directories/ =>
+          "ヒント: パスは workspace/ で始まる相対パスにしてください (例: workspace/foo.txt)。" \
+          "workspace の外や絶対パスは使えません。",
+        /command not allowed/ =>
+          "ヒント: run_command で使えるコマンドは whitelist に登録されたものだけです。" \
+          "許可されていないコマンド (bash 等) を run_command で実行しようとしないでください。" \
+          "シェル機能が必要な場合は bash/powershell ツールを直接使ってください。",
+        /old_string not found|old_string is not unique/ =>
+          "ヒント: edit の old_string はファイルの現在の内容と完全一致し、かつ一意である必要があります。" \
+          "前回の置換が既に成功している可能性があるので、まず read_file で現在の内容を確認してください。"
+      }.freeze
+
+      def failure_hints(history)
+        errors = history.filter_map { |h| h[:error]&.to_s }
+        matched = FAILURE_HINTS.filter_map { |pattern, hint| hint if errors.any? { |e| e.match?(pattern) } }
+        matched.join("\n")
+      end
+
+      # feedback を試行履歴の配列に正規化する (旧来の単一 Hash も受理)。
+      def normalize_history(feedback)
+        case feedback
+        when nil then []
+        when Array then feedback
+        else [feedback]
+        end
+      end
+
+      def from_tool_use(response)
+        blocks = Array(response["content"])
+        tu = blocks.find { |b| b.is_a?(Hash) && b["type"] == "tool_use" }
+        return nil unless tu
+
+        args = tu["input"]
+        args = {} if args.nil?
+        raise InvalidProposalError, "arguments must be an object" unless args.is_a?(Hash)
+
+        { "tool" => tu["name"], "arguments" => args }
+      end
+
+      # モデルがツールを使わず自然文だけで応答したとき、その文章を最終メッセージとして
+      # finish 提案に載せて返す。ツール不要で答えられた場合や、必要な情報 (場所など) を
+      # ユーザーに聞き返す場合がこれに当たる。thinking ブロックは除き本文テキストのみ拾う。
+      #
+      # モデルがツール呼び出し JSON を書き損じた残骸 ({..}, <|..|> 等) が混じることが
+      # あるため、それらを取り除いて読みやすくする。除去後に実質空になったら、
+      # 汎用の聞き返し文にフォールバックする (壊れた断片をそのまま見せない)。
+      def from_text_reply(response)
+        text = clean_reply_text(extract_text(response).to_s)
+        text = "うまく指示を解釈できませんでした。もう少し具体的に教えてください。" if text.empty?
+
+        { "tool" => FINISH_TOOL, "arguments" => { "message" => text } }
+      end
+
+      # 自然文応答から、ツール呼び出し JSON の書き損じ残骸を取り除く。
+      def clean_reply_text(text)
+        text.gsub(/\{[^{}]*\}/, " ")          # {reason:...} のような JSON 断片
+            .gsub(/<\|[^|]*\|>/, " ")          # <|"|> のような特殊トークン
+            .gsub(/[ \t]{2,}/, " ")
+            .strip
+      end
+
+      # content 内テキスト、または文字列レスポンスから JSON オブジェクトを拾う。
+      # strict: true なら JSON 抽出失敗 (壊れた JSON / tool・arguments 欠落) を
+      # InvalidProposalError にする。false なら nil を返し、呼び出し側の別経路
+      # (自然文応答の扱い) にフォールバックさせる。
+      def from_text(response, strict: true)
+        text = extract_text(response)
+        return nil if text.nil? || text.empty?
+
+        json = extract_json_object(text)
+        return nil if json.nil?
+
+        parsed = JSON.parse(json)
+        unless parsed.is_a?(Hash) && parsed["tool"] && parsed["arguments"].is_a?(Hash)
+          return nil unless strict
+
+          raise InvalidProposalError, "proposal JSON missing tool/arguments"
+        end
+
+        { "tool" => parsed["tool"], "arguments" => parsed["arguments"] }
+      rescue JSON::ParserError => e
+        return nil unless strict
+
+        raise InvalidProposalError, "proposal JSON invalid: #{e.message}"
+      end
+
+      def extract_text(response)
+        blocks = Array(response["content"])
+        texts = blocks.filter_map do |b|
+          b["text"] if b.is_a?(Hash) && b["type"] == "text"
+        end
+        return texts.join("\n") unless texts.empty?
+
+        response["content"].is_a?(String) ? response["content"] : nil
+      end
+
+      # 最初の { から対応する } までを素朴に切り出す。
+      def extract_json_object(text)
+        start = text.index("{")
+        return nil unless start
+
+        depth = 0
+        text[start..].each_char.with_index do |ch, i|
+          depth += 1 if ch == "{"
+          depth -= 1 if ch == "}"
+          return text[start, i + 1] if depth.zero?
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/chocomint/llm/verifier_client.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Chocomint
+  module LLM
+    # 副 LLM による意味的検証 (DESIGN §4)。1 または 0 のみを返させる。
+    class VerifierClient
+      PROMPT_TEMPLATE = <<~PROMPT
+        あなたは厳格な監査器です。
+
+        ユーザー要求:
+        %<request>s
+
+        期待条件:
+        %<expectations>s
+
+        実行結果:
+        %<result>s
+
+        要求が完全に満たされている場合のみ 1 を返してください。
+        少しでも不明点・不足・失敗の可能性がある場合は 0 を返してください。
+        exit_code が 0 で stdout が要求を満たしていれば、stderr に警告・ログめいた
+        文字列が含まれていても、それだけを理由に不合格にしないでください。
+
+        出力は 1 または 0 のみ。
+      PROMPT
+
+      # マルチステップ全体の達成判定プロンプト。
+      # 単一結果ではなく、これまで実行した全ステップを踏まえて要求全体を評価させる。
+      OVERALL_TEMPLATE = <<~PROMPT
+        あなたは厳格な監査器です。
+
+        ユーザー要求:
+        %<request>s
+
+        期待条件:
+        %<expectations>s
+
+        これまでに実行が完了したステップ (順番どおり):
+        %<steps>s
+
+        上記のステップ実行の結果として、ユーザー要求が「全体として完全に」満たされたかを判定してください。
+        まだ実行すべき作業が残っている、または要求の一部しか満たされていない場合は 0 を返してください。
+        要求が過不足なくすべて達成されている場合のみ 1 を返してください。
+
+        出力は 1 または 0 のみ。
+      PROMPT
+
+      def initialize(base_client:)
+        @client = base_client
+      end
+
+      # マルチステップ全体の達成判定。戻り値: "1" / "0" / nil(不正 -> 未達成扱い)。
+      # done_steps: [{ tool:, arguments:, result: }, ...] 形式の完了済みステップ列。
+      def verify_overall(request:, done_steps:, expectations: nil, trace_id: nil)
+        prompt = format(
+          OVERALL_TEMPLATE,
+          request: request.to_s,
+          expectations: (expectations || "(なし)").to_s,
+          steps: serialize_steps(done_steps)
+        )
+
+        response = @client.create_message(
+          messages: [{ "role" => "user", "content" => prompt }],
+          trace_id: trace_id
+        )
+
+        normalize(extract_text(response))
+      end
+
+      # 戻り値: "1" / "0" / nil(不正出力 -> RETRY 扱い)
+      def verify(request:, result:, expectations: nil, trace_id: nil)
+        prompt = format(
+          PROMPT_TEMPLATE,
+          request: request.to_s,
+          expectations: (expectations || "(なし)").to_s,
+          result: serialize(result)
+        )
+
+        response = @client.create_message(
+          messages: [{ "role" => "user", "content" => prompt }],
+          trace_id: trace_id
+        )
+
+        normalize(extract_text(response))
+      end
+
+      private
+
+      # strip 後に完全一致で "1"/"0" のみ許可、それ以外は nil。
+      def normalize(text)
+        return nil if text.nil?
+
+        t = text.strip
+        %w[1 0].include?(t) ? t : nil
+      end
+
+      def extract_text(response)
+        blocks = Array(response["content"])
+        texts = blocks.filter_map do |b|
+          b["text"] if b.is_a?(Hash) && b["type"] == "text"
+        end
+        return texts.join.strip unless texts.empty?
+
+        response["content"].is_a?(String) ? response["content"] : nil
+      end
+
+      def serialize(result)
+        result.is_a?(String) ? result : JSON.generate(result)
+      end
+
+      # 完了ステップ列を判定プロンプト向けに整形する。
+      def serialize_steps(done_steps)
+        steps = Array(done_steps)
+        return "(なし)" if steps.empty?
+
+        steps.each_with_index.map do |s, i|
+          tool = s[:tool] || s["tool"]
+          args = s[:arguments] || s["arguments"]
+          result = s[:result] || s["result"]
+          "ステップ#{i + 1}: ツール=#{tool} 引数=#{serialize(args)} 結果=#{serialize(result)}"
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/chocomint/logger/sqlite_logger.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+require "json"
+require "time"
+require "fileutils"
+
+module Chocomint
+  module Logger
+    # 全試行を SQLite に記録する (DESIGN §12)。
+    class SqliteLogger
+      def initialize(path)
+        FileUtils.mkdir_p(File.dirname(path)) unless File.dirname(path).empty?
+        @db = SQLite3::Database.new(path)
+        create_schema
+      end
+
+      # 1 attempt を 1 行として保存する。
+      def record(trace_id:, attempt:, request:, proposal:, result:, status:, verifier_output: nil)
+        @db.execute(
+          <<~SQL,
+            INSERT INTO executions
+              (trace_id, attempt, request, proposal, result, verifier_output, status, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          SQL
+          [
+            trace_id,
+            attempt,
+            request.to_s,
+            serialize(proposal),
+            serialize(result),
+            verifier_output,
+            status,
+            Time.now.utc.iso8601
+          ]
+        )
+      end
+
+      # LLM への送信内容 (ヘッダ含む生ボディ全体) を 1 呼び出し 1 行で記録する。
+      # role: "primary" / "verifier"。body/headers は Hash を渡すと JSON 化する。
+      # 戻り値: 挿入した行の id (後で update_llm_payload_response に渡す)。
+      def record_llm_payload(role:, model:, request_body:, request_headers:, trace_id: nil)
+        @db.execute(
+          <<~SQL,
+            INSERT INTO llm_payloads
+              (trace_id, role, model, request_body, request_headers, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+          SQL
+          [
+            trace_id,
+            role.to_s,
+            model.to_s,
+            serialize(request_body),
+            serialize(request_headers),
+            Time.now.utc.iso8601
+          ]
+        )
+        @db.last_insert_row_id
+      end
+
+      # 記録済みペイロード行に LLM レスポンス (HTTP ステータス + 生ボディ) を追記する。
+      # id は record_llm_payload の戻り値。body は文字列/Hash どちらも可。
+      def update_llm_payload_response(id, response_status:, response_body:)
+        return if id.nil?
+
+        @db.execute(
+          "UPDATE llm_payloads SET response_status = ?, response_body = ? WHERE id = ?",
+          [response_status, serialize(response_body), id]
+        )
+      end
+
+      # LLM 送信ペイロードを新しい順に取得する。trace_id で絞り込み可能。
+      def recent_llm_payloads(limit: 100, offset: 0, trace_id: nil)
+        trace_id = normalize_text(trace_id)
+        where = trace_id ? "WHERE trace_id = ?" : ""
+        params = trace_id ? [trace_id, limit, offset] : [limit, offset]
+        @db.results_as_hash = true
+        @db.execute(
+          <<~SQL,
+            SELECT id, trace_id, role, model, request_body, request_headers,
+                   response_status, response_body, created_at
+            FROM llm_payloads
+            #{where}
+            ORDER BY id DESC
+            LIMIT ? OFFSET ?
+          SQL
+          params
+        )
+      ensure
+        @db.results_as_hash = false
+      end
+
+      # trace_id に紐づくツール実行の正常性判定 (status / verifier_output) を
+      # attempt 昇順で返す。LLM ペイロード詳細で「判定結果」を併記するため。
+      def tool_outcomes(trace_id)
+        trace_id = normalize_text(trace_id)
+        return [] if trace_id.nil?
+
+        @db.results_as_hash = true
+        @db.execute(
+          <<~SQL,
+            SELECT attempt, status, verifier_output, proposal
+            FROM executions WHERE trace_id = ?
+            ORDER BY attempt ASC, id ASC
+          SQL
+          [trace_id]
+        )
+      ensure
+        @db.results_as_hash = false
+      end
+
+      # LLM ペイロード 1 件を id 指定で取得する。無ければ nil。
+      def llm_payload(id)
+        @db.results_as_hash = true
+        @db.execute(
+          <<~SQL,
+            SELECT id, trace_id, role, model, request_body, request_headers,
+                   response_status, response_body, created_at
+            FROM llm_payloads WHERE id = ?
+          SQL
+          [id]
+        ).first
+      ensure
+        @db.results_as_hash = false
+      end
+
+      # LLM ペイロードの総件数。trace_id 指定時はその trace の件数。
+      def llm_payload_count(trace_id: nil)
+        trace_id = normalize_text(trace_id)
+        if trace_id
+          @db.execute("SELECT COUNT(*) FROM llm_payloads WHERE trace_id = ?", [trace_id])
+        else
+          @db.execute("SELECT COUNT(*) FROM llm_payloads")
+        end.first.first
+      end
+
+      # 監査ログを新しい順に取得する。ブラウザ表示 (GET /logs) 用。
+      # trace_id を指定するとその trace のみに絞る。offset でページ送り。
+      # 返り値は各行を Hash(カラム名 => 値) にした配列。
+      def recent(limit: 100, offset: 0, trace_id: nil)
+        trace_id = normalize_text(trace_id)
+        where = trace_id ? "WHERE trace_id = ?" : ""
+        params = trace_id ? [trace_id, limit, offset] : [limit, offset]
+        @db.results_as_hash = true
+        @db.execute(
+          <<~SQL,
+            SELECT id, trace_id, attempt, request, proposal, result,
+                   verifier_output, status, created_at
+            FROM executions
+            #{where}
+            ORDER BY id DESC
+            LIMIT ? OFFSET ?
+          SQL
+          params
+        )
+      ensure
+        @db.results_as_hash = false
+      end
+
+      # 監査ログ 1 件を id 指定で取得する。無ければ nil。
+      def execution(id)
+        @db.results_as_hash = true
+        @db.execute(
+          <<~SQL,
+            SELECT id, trace_id, attempt, request, proposal, result,
+                   verifier_output, status, created_at
+            FROM executions WHERE id = ?
+          SQL
+          [id]
+        ).first
+      ensure
+        @db.results_as_hash = false
+      end
+
+      # ページネーション用の総件数。trace_id 指定時はその trace の件数。
+      def count(trace_id: nil)
+        trace_id = normalize_text(trace_id)
+        if trace_id
+          @db.execute("SELECT COUNT(*) FROM executions WHERE trace_id = ?", [trace_id])
+        else
+          @db.execute("SELECT COUNT(*) FROM executions")
+        end.first.first
+      end
+
+      def close = @db.close
+
+      private
+
+      # TEXT カラムと確実に比較できるよう UTF-8 文字列に正規化する。
+      # ASCII-8BIT(BINARY) のままだと sqlite3 が BLOB としてバインドし、
+      # TEXT カラムと一致しなくなる。
+      def normalize_text(str)
+        return nil if str.nil?
+
+        str.encoding == Encoding::UTF_8 ? str : str.dup.force_encoding("UTF-8")
+      end
+
+      def create_schema
+        @db.execute <<~SQL
+          CREATE TABLE IF NOT EXISTS executions (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            trace_id TEXT NOT NULL,
+            attempt INTEGER NOT NULL,
+            request TEXT NOT NULL,
+            proposal TEXT NOT NULL,
+            result TEXT NOT NULL,
+            verifier_output TEXT,
+            status TEXT NOT NULL,
+            created_at TEXT NOT NULL
+          )
+        SQL
+        @db.execute <<~SQL
+          CREATE TABLE IF NOT EXISTS llm_payloads (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            trace_id TEXT,
+            role TEXT NOT NULL,
+            model TEXT NOT NULL,
+            request_body TEXT NOT NULL,
+            request_headers TEXT NOT NULL,
+            response_status INTEGER,
+            response_body TEXT,
+            created_at TEXT NOT NULL
+          )
+        SQL
+        # 既存 DB へのカラム追加 (存在すれば無視)。
+        add_column_if_missing("llm_payloads", "response_status", "INTEGER")
+        add_column_if_missing("llm_payloads", "response_body", "TEXT")
+      end
+
+      def serialize(obj)
+        return obj if obj.is_a?(String)
+
+        JSON.generate(obj)
+      end
+
+      # 既存テーブルに列が無ければ追加する (旧 DB の後方互換マイグレーション)。
+      def add_column_if_missing(table, column, type)
+        cols = @db.execute("PRAGMA table_info(#{table})").map { |r| r[1] }
+        return if cols.include?(column)
+
+        @db.execute("ALTER TABLE #{table} ADD COLUMN #{column} #{type}")
+      end
+    end
+  end
+end