harnex 0.8.0 → 0.9.0

data/lib/harnex/adapters/base.rb

@@ -37,6 +37,16 @@ module Harnex
         nil
       end
 
+      # Whether the usage this adapter captures reports input_tokens
+      # INCLUSIVE of cached_tokens. Depends on the capture path, not just
+      # the provider: codex app-server JSON reports cached as a subset of
+      # input, while the codex TUI line the PTY adapter scrapes shows
+      # non-cached input with cached as a separate additive count. Feeds
+      # Pricing.compute (plan 33 Phase 2).
+      def usage_input_includes_cached?
+        false
+      end
+
       # Probes `<base_command.first> --version` with a short timeout and
       # memoizes the result for the adapter's lifetime. Returns nil when
       # the binary is missing, exits non-zero, or stalls past the timeout.

data/lib/harnex/adapters/codex_appserver.rb

@@ -59,6 +59,7 @@ module Harnex
         @initial_prompt = extract_initial_prompt(extra_args)
         @client = nil
         @thread_id = nil
+        @current_model = nil
         @current_turn_id = nil
         @state = :disconnected
         @last_completed_at = nil
@@ -78,6 +79,21 @@ module Harnex
         true
       end
 
+      # thread/tokenUsage/updated totals report cachedInputTokens as a
+      # subset of inputTokens (verified against a live captured row:
+      # input + output == total exactly, cached < input).
+      def usage_input_includes_cached?
+        true
+      end
+
+      # Effective model reported by the app-server's thread/start or
+      # thread/resume response (schema-required field). Feeds
+      # Session#summary_model so price-table cost can resolve without the
+      # caller passing `--meta '{"model": ...}'`.
+      def current_model
+        @current_model
+      end
+
       def context_telemetry_supported?
         true
       end
@@ -202,6 +218,7 @@ module Harnex
         ensure_open!
         result = @client.request("thread/resume", { threadId: thread_id })
         @thread_id = thread_id
+        @current_model = extract_model(result) || @current_model
         @state = :prompt
         result
       end
@@ -279,6 +296,7 @@ module Harnex
 
         result = @client.request("thread/start", {})
         @thread_id = extract_thread_id(result)
+        @current_model = extract_model(result) || @current_model
       end
 
       def extract_thread_id(payload)
@@ -287,6 +305,13 @@ module Harnex
         payload.dig("thread", "id")
       end
 
+      def extract_model(payload)
+        return nil unless payload.is_a?(Hash)
+
+        model = payload["model"]
+        model.is_a?(String) && !model.empty? ? model : nil
+      end
+
       def extract_initial_prompt(extra_args)
         return nil unless extra_args.is_a?(Array)
 

data/lib/harnex/commands/doctor.rb

@@ -7,7 +7,7 @@ module Harnex
 
     def self.usage
       <<~TEXT
-        Usage: harnex doctor [--sweep]
+        Usage: harnex doctor [--sweep] [--prune [--dry-run]]
 
         Runs preflight checks for harnex's adapter dependencies.
         Currently verifies that Codex CLI is installed and at version
@@ -16,16 +16,21 @@ module Harnex
 
         Options:
           --sweep      Include a read-only report of harnex/tmux session drift
+          --prune      Apply bounded harnex events/output retention pruning
+          --dry-run    Preview --prune candidates without deleting
           -h, --help   Show this help
 
         Common patterns:
           harnex doctor
           harnex doctor --sweep
+          harnex doctor --prune --dry-run
+          harnex doctor --prune
           harnex doctor --help
 
         Gotchas:
           doctor validates local adapter prerequisites; it does not start sessions.
           --sweep is diagnostic only; it does not stop sessions or remove files.
+          --dry-run must be paired with --prune.
           Run it after installing or upgrading Codex CLI.
       TEXT
     end
@@ -34,21 +39,26 @@ module Harnex
       @argv = argv.dup
       @options = {
         sweep: false,
+        prune: false,
+        dry_run: false,
         help: false
       }
     end
 
     def run
       parser.parse!(@argv)
+      validate_options!
       if @options[:help]
         puts self.class.usage
         return 0
       end
 
       checks = [check_codex]
+      retention = retention_payload
       summary = {
-        ok: checks.all? { |c| c[:ok] },
-        checks: checks
+        ok: checks.all? { |c| c[:ok] } && retention.fetch(:ok, true),
+        checks: checks,
+        retention: retention
       }
       summary[:sweep] = sweep_payload if @options[:sweep]
       puts JSON.generate(summary)
@@ -59,12 +69,36 @@ module Harnex
 
     def parser
       @parser ||= OptionParser.new do |opts|
-        opts.banner = "Usage: harnex doctor [--sweep]"
+        opts.banner = "Usage: harnex doctor [--sweep] [--prune [--dry-run]]"
         opts.on("--sweep", "Include read-only session drift diagnostics") { @options[:sweep] = true }
+        opts.on("--prune", "Apply retention pruning") { @options[:prune] = true }
+        opts.on("--dry-run", "Preview --prune candidates without deleting") { @options[:dry_run] = true }
         opts.on("-h", "--help", "Show help") { @options[:help] = true }
       end
     end
 
+    def validate_options!
+      return if @options[:help]
+      return unless @options[:dry_run] && !@options[:prune]
+
+      raise OptionParser::InvalidOption, "--dry-run requires --prune"
+    end
+
+    def retention_payload
+      repo_root = Harnex.resolve_repo_root(Dir.pwd)
+      if @options[:prune]
+        Harnex::Retention.prune(
+          repo_root: repo_root,
+          dry_run: @options[:dry_run],
+          force: true
+        )
+      else
+        Harnex::Retention.status(repo_root: repo_root)
+      end
+    rescue Harnex::Config::ConfigError => e
+      { ok: false, error: e.message }
+    end
+
     def check_codex
       result = { name: "codex", required: ">= #{MIN_CODEX_VERSION}" }
 

data/lib/harnex/commands/history.rb

@@ -85,6 +85,7 @@ module Harnex
     # One row per dispatch: start rows completed by an end row are dropped
     # (the end row carries the outcome); uncompleted start rows surface as
     # running (pid alive on this host) or interrupted (no end row, pid gone).
+    # Rows in neither shape (pre-0.7.3 schemas) are skipped entirely.
     def derived_records
       raw = load_records
       ended = Set.new
@@ -97,10 +98,13 @@ module Harnex
       end
 
       raw.filter_map do |record|
-        next record unless DispatchHistory.start_record?(record)
-        next nil if start_completed?(record, ended)
+        if DispatchHistory.start_record?(record)
+          next nil if start_completed?(record, ended)
 
-        derive_live_record(record)
+          derive_live_record(record)
+        elsif DispatchHistory.end_record?(record)
+          record
+        end
       end
     end
 

data/lib/harnex/commands/run.rb

@@ -39,7 +39,7 @@ module Harnex
 
     # Attempt kinds that redo the parent's work; dispatching one while the
     # parent is still running duplicates work in the same checkout.
-    LIVE_PARENT_GUARDED_KINDS = %w[retry fix superseding].freeze
+    LIVE_PARENT_GUARDED_KINDS = %w[retry fix fallback superseding].freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
       --max-resumes --preset --context --meta --summary-out --artifact-report
@@ -67,7 +67,7 @@ module Harnex
           --fast             (codex only) Use Codex service_tier="fast".
                              Default Codex runs force service_tier="flex".
           --meta JSON        Attach parsed JSON metadata to the started event
-          --summary-out PATH Append dispatch telemetry summary JSONL to PATH
+          --summary-out PATH Also mirror the dispatch end record JSONL to PATH
           --artifact-report PATH
                              Worker-written harnex.artifact_report.v1 JSON sidecar to ingest at exit
           --validation-report PATH
@@ -87,12 +87,12 @@ module Harnex
           --model NAME       Requested model metadata (also used for structured dispatch)
           --effort LEVEL     Requested reasoning effort metadata (structured dispatch)
           --parent-dispatch-id ID
-                             Parent dispatch id for retry/fix/review joins
+                             Parent dispatch id for retry/fix/review/fallback joins
           --parent-attempt-id ID
-                             Parent attempt id for retry/fix/review joins
+                             Parent attempt id for retry/fix/review/fallback joins
           --attempt-kind KIND
-                             initial, retry, fix, review, or superseding (default: initial).
-                             retry requires --parent-dispatch-id so the
+                             initial, retry, fix, review, fallback, or superseding (default: initial).
+                             retry/fallback requires --parent-dispatch-id so the
                              duplicate-dispatch guard can verify the parent
           --allow-live-parent
                              Dispatch even though --parent-dispatch-id names a
@@ -203,6 +203,7 @@ module Harnex
       validate_required_attribution!
 
       repo_root = resolve_run_root(cli_name, child_args)
+      validate_repo_phase_policy!(repo_root)
       @options[:summary_out] = resolve_summary_out(repo_root)
       @options[:artifact_report] = resolve_artifact_report(repo_root)
       @options[:id] ||= Harnex.generate_id(repo_root)
@@ -371,7 +372,7 @@ module Harnex
             "Use a different --id or stop the existing session first."
     end
 
-    # Duplicate-dispatch guard (issue #62): a retry/fix/superseding attempt
+    # Duplicate-dispatch guard (issue #62): a retry/fix/fallback/superseding attempt
     # whose parent dispatch is still running would duplicate work in the same
     # checkout. Explicit --parent-dispatch-id only — the implicit HARNEX_ID
     # lineage of a live spawner must not trip this.
@@ -380,8 +381,8 @@ module Harnex
       kind = metadata["attempt_kind"].to_s
       parent_id = metadata["parent_dispatch_id"].to_s.strip
 
-      if kind == "retry" && parent_id.empty?
-        raise "harnex run: --attempt-kind retry requires --parent-dispatch-id " \
+      if %w[retry fallback].include?(kind) && parent_id.empty?
+        raise "harnex run: --attempt-kind #{kind} requires --parent-dispatch-id " \
               "so the duplicate-dispatch guard can verify the parent is not still running."
       end
 
@@ -398,6 +399,30 @@ module Harnex
             "or pass --allow-live-parent for intentional parallelism."
     end
 
+    def validate_repo_phase_policy!(repo_root)
+      config = Harnex::Config.load_repo(repo_root)
+      Harnex::Config.retention_limits(config: config)
+      phase_config = config.phase
+      return unless phase_config
+
+      metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
+      phase = metadata["phase"].to_s
+      allowlist = phase_config.fetch("allowlist")
+      return if allowlist.include?(phase)
+
+      policy = phase_config.fetch("policy")
+      message = "harnex run: meta.phase #{phase.empty? ? '(none)' : phase.inspect} " \
+                "is not allowlisted by #{config.path} " \
+                "(allowed: #{allowlist.join(', ')}; policy: #{policy})"
+      if policy == "warn"
+        warn("harnex: warning: #{message}")
+      else
+        raise OptionParser::InvalidOption, message
+      end
+    rescue Harnex::Config::ConfigError => e
+      raise OptionParser::InvalidOption, "harnex run: invalid config #{e.message}"
+    end
+
     def build_session(adapter, repo_root)
       watch = Harnex.build_watch_config(@options[:watch], repo_root)
       Session.new(
@@ -842,9 +867,11 @@ module Harnex
       raise OptionParser::InvalidOption, "--meta must be valid JSON: #{e.message}"
     end
 
+    # Explicit-only mirror: the tracked dispatch stream is the canonical
+    # destination; --summary-out just duplicates the end record elsewhere.
     def resolve_summary_out(repo_root)
       configured = @options[:summary_out]
-      return Harnex.default_summary_out_path(repo_root) if configured.nil?
+      return nil if configured.nil?
 
       File.expand_path(configured, repo_root)
     end

data/lib/harnex/config.rb

@@ -0,0 +1,166 @@
+require "json"
+
+module Harnex
+  module Config
+    CONFIG_RELATIVE_PATH = File.join(".harnex", "config.json").freeze
+    PHASE_POLICIES = %w[warn reject].freeze
+    RETENTION_DIRS = %w[events output].freeze
+    RETENTION_FIELDS = %w[max_age_days max_bytes].freeze
+    RETENTION_ENV = {
+      "events" => {
+        "max_age_days" => "HARNEX_EVENTS_MAX_AGE_DAYS",
+        "max_bytes" => "HARNEX_EVENTS_MAX_BYTES"
+      },
+      "output" => {
+        "max_age_days" => "HARNEX_OUTPUT_MAX_AGE_DAYS",
+        "max_bytes" => "HARNEX_OUTPUT_MAX_BYTES"
+      }
+    }.freeze
+    DEFAULT_RETENTION_LIMITS = RETENTION_DIRS.to_h do |dir|
+      [dir, { "max_age_days" => 45, "max_bytes" => 1_073_741_824 }]
+    end.freeze
+
+    ConfigError = Class.new(StandardError)
+
+    RepoConfig = Struct.new(:root, :path, :data, keyword_init: true) do
+      def present?
+        !path.nil? && File.file?(path)
+      end
+
+      def phase
+        data.is_a?(Hash) ? data["phase"] : nil
+      end
+
+      def retention
+        data.is_a?(Hash) ? data["retention"] : nil
+      end
+    end
+
+    module_function
+
+    def load_repo(start_path)
+      root = DispatchHistory.find_git_root(start_path)
+      return RepoConfig.new(root: nil, path: nil, data: {}) unless root
+
+      path = File.join(root, CONFIG_RELATIVE_PATH)
+      return RepoConfig.new(root: root, path: path, data: {}) unless File.file?(path)
+
+      parsed = JSON.parse(File.read(path))
+      validate_document!(parsed, path)
+      RepoConfig.new(root: root, path: path, data: parsed)
+    rescue JSON::ParserError => e
+      raise ConfigError, "#{path}: malformed JSON: #{e.message}"
+    end
+
+    def validate_document!(document, path)
+      unless document.is_a?(Hash)
+        raise ConfigError, "#{path}: config must be a JSON object"
+      end
+
+      validate_phase!(document["phase"], path) if document.key?("phase")
+      validate_retention!(document["retention"], path) if document.key?("retention")
+    end
+
+    def validate_phase!(phase, path)
+      unless phase.is_a?(Hash)
+        raise ConfigError, "#{path}: $.phase must be an object"
+      end
+
+      allowlist = phase["allowlist"]
+      unless allowlist.is_a?(Array)
+        raise ConfigError, "#{path}: $.phase.allowlist must be an array"
+      end
+
+      allowlist.each_with_index do |entry, index|
+        next if entry.is_a?(String) && !entry.strip.empty?
+
+        raise ConfigError,
+          "#{path}: $.phase.allowlist[#{index}] must be a non-empty string"
+      end
+
+      policy = phase["policy"]
+      unless PHASE_POLICIES.include?(policy)
+        raise ConfigError,
+          "#{path}: $.phase.policy must be one of #{PHASE_POLICIES.join(', ')}"
+      end
+    end
+
+    def retention_limits(start_path = Dir.pwd, env: ENV, config: nil)
+      config ||= load_repo(start_path)
+      limits = deep_dup_retention_defaults
+      retention = config.retention
+
+      if retention
+        RETENTION_DIRS.each do |dir|
+          next unless retention.key?(dir)
+
+          RETENTION_FIELDS.each do |field|
+            next unless retention.fetch(dir).key?(field)
+
+            limits.fetch(dir)[field] = parse_positive_integer!(
+              retention.fetch(dir).fetch(field),
+              "#{config.path}: $.retention.#{dir}.#{field}"
+            )
+          end
+        end
+      end
+
+      RETENTION_ENV.each do |dir, fields|
+        fields.each do |field, name|
+          next unless env.key?(name)
+
+          limits.fetch(dir)[field] = parse_positive_integer!(
+            env.fetch(name),
+            name
+          )
+        end
+      end
+
+      limits
+    end
+
+    def validate_retention!(retention, path)
+      unless retention.is_a?(Hash)
+        raise ConfigError, "#{path}: $.retention must be an object"
+      end
+
+      retention.each do |dir, value|
+        unless RETENTION_DIRS.include?(dir)
+          raise ConfigError,
+            "#{path}: $.retention.#{dir} is not supported (expected events or output)"
+        end
+        unless value.is_a?(Hash)
+          raise ConfigError, "#{path}: $.retention.#{dir} must be an object"
+        end
+
+        value.each do |field, limit|
+          unless RETENTION_FIELDS.include?(field)
+            raise ConfigError,
+              "#{path}: $.retention.#{dir}.#{field} is not supported"
+          end
+
+          parse_positive_integer!(
+            limit,
+            "#{path}: $.retention.#{dir}.#{field}"
+          )
+        end
+      end
+    end
+
+    def parse_positive_integer!(value, label)
+      text = value.to_s.strip
+      unless text.match?(/\A[0-9]+\z/)
+        raise ConfigError, "#{label} must be a positive integer"
+      end
+
+      integer = Integer(text)
+      raise ConfigError, "#{label} must be a positive integer" if integer <= 0
+
+      integer
+    end
+
+    def deep_dup_retention_defaults
+      DEFAULT_RETENTION_LIMITS.transform_values(&:dup)
+    end
+  end
+end

data/lib/harnex/core.rb

@@ -114,13 +114,6 @@ module Harnex
     text.to_s.gsub(/\e\[[0-9;]*[a-zA-Z]/, "")
   end
 
-  def default_summary_out_path(repo_root)
-    root = repo_root.to_s
-    return nil if root.empty?
-
-    File.join(root, ".harnex", "dispatch.jsonl")
-  end
-
   def git_capture_start(repo_root)
     sha = git_output(repo_root, "rev-parse", "HEAD")
     branch = git_output(repo_root, "rev-parse", "--abbrev-ref", "HEAD")

data/lib/harnex/dispatch_history.rb

@@ -9,6 +9,12 @@ module Harnex
 
     MAX_REPO_WALK_LEVELS = 10
 
+    # v2 marks the unified era: one rich dispatch_end row per dispatch
+    # carrying both the thin envelope and the summary sections. Readers
+    # key on record_type, not this stamp; legacy clauses keep accepting
+    # v1 and envelope-less rows mixed in the same file.
+    SCHEMA_VERSION = 2
+
     def global_path
       File.join(STATE_DIR, "dispatch.jsonl")
     end
@@ -138,7 +144,7 @@ module Harnex
     # trace; the dispatch_end row written in finalize_session! completes it.
     def build_start_record(session)
       {
-        schema_version: 1,
+        schema_version: SCHEMA_VERSION,
         record_type: "dispatch_start",
         id: session.id,
         session_id: session.session_id,
@@ -155,11 +161,15 @@ module Harnex
       }
     end
 
+    # The v2 end row: the thin envelope merged with the rich summary
+    # sections. The envelope carries no raw meta passthrough — the summary's
+    # meta section (a superset with provenance) rides in its place; top-level
+    # tier stays for the history renderer.
     def build_record(session)
       ended_at = session.ended_at || Time.now
       status, terminal_event = classify(session)
       {
-        schema_version: 1,
+        schema_version: SCHEMA_VERSION,
         record_type: "dispatch_end",
         id: session.id,
         session_id: session.session_id,
@@ -172,11 +182,10 @@ module Harnex
         terminal_event: terminal_event,
         commit_sha: commit_sha(session.git_start, session.git_end),
         tier: session.__send__(:meta_hash)["tier"],
-        meta: session.__send__(:meta_hash),
         summary_out_path: session.summary_out,
         events_log_path: session.events_log_path,
         tmux_state: tmux_state(session.__send__(:summary_tmux_session))
-      }
+      }.merge(session.__send__(:build_summary_record))
     end
 
     def classify(session)

data/lib/harnex/pricing.rb

@@ -0,0 +1,135 @@
+module Harnex
+  # Static price table for computing usage.cost_usd when an adapter reports
+  # tokens but no cost (plan 33 Phase 2, locked decision 6). Cost is computed,
+  # never guessed: an unknown provider/model/service tier or a missing token
+  # component leaves cost_usd null.
+  #
+  # ## Update procedure
+  #
+  # Rates are USD per 1M tokens, copied by hand from the provider pricing
+  # pages at the URLs below. To update:
+  #
+  # 1. Fetch the provider's pricing page and read the per-1M-token rates for
+  #    input, cached input (cache read), and output.
+  # 2. Replace the entry's rates and set `as_of` to the date you read them.
+  #    Add new models as new entries; never delete an entry solely because a
+  #    model left the pricing page (old rows in dispatch.jsonl were priced
+  #    against it — the `as_of` on each row records which table vintage
+  #    applied).
+  # 3. Update the expected costs in test/harnex/pricing_test.rb — rate
+  #    changes are meant to be conscious, test-visible edits.
+  # 4. Never backfill: rows written before a table change keep the cost they
+  #    were written with.
+  #
+  # Models whose pricing varies by service tier use a nested `service_tiers`
+  # table. For those models a nil or unknown service tier is unpriceable. A
+  # `max_context_tokens_exclusive` entry also requires an observed context
+  # high-water below that boundary; Harnex leaves cost null when context is
+  # missing or entered a differently-priced long-context tier. Do not infer
+  # standard/flex/fast or context tier outside the recorded measurements.
+  # OpenAI documents `priority` as the fast alias for gpt-5.5 short-context
+  # pricing; Harnex maps that alias only where the source supports it.
+  #
+  # Known scheduled change: Anthropic's claude-sonnet-5 entry below carries
+  # introductory pricing ($2/$10) that ends 2026-08-31; standard pricing is
+  # $3/$15 (cache read $0.30) from 2026-09-01. Refresh the entry then.
+  #
+  # ## Token semantics (verified 2026-08-02, plan 33 Phase 2)
+  #
+  # What input_tokens contains depends on the CAPTURE PATH, not just the
+  # provider, so the caller passes `input_includes_cached:` (sourced from
+  # `Adapters::Base#usage_input_includes_cached?`):
+  #
+  # - codex app-server (input_includes_cached: true): the JSON
+  #   TokenUsageBreakdown reports cachedInputTokens as a subset of
+  #   inputTokens and reasoningOutputTokens as a subset of outputTokens
+  #   (verified against test/fixtures/codex_schema/v2 and a live captured
+  #   row: input 3,084,697 + output 17,705 == total 3,102,402 exactly).
+  #   Billable input = input - cached.
+  # - codex PTY (false): the scraped TUI line `input=X (+ Y cached)` shows
+  #   NON-cached input with cached as a separate additive count (fixture:
+  #   total 106,867 == input 104,158 + output 2,709, cached 250,880 > input).
+  #   Billable input = input; cached prices additively at the cached rate.
+  # - anthropic (false): the Messages API reports input_tokens EXCLUSIVE of
+  #   cache reads (cache_read_input_tokens is a separate field). Cache
+  #   WRITES (cache_creation_input_tokens, billed at 1.25x input) have no
+  #   harnex usage field yet — the Phase 3 Claude usage producer must either
+  #   fold them into input_tokens or extend this formula before pricing rows
+  #   that include cache writes.
+  #
+  # Reasoning tokens are never priced separately on any path — they are
+  # already inside output_tokens.
+  module Pricing
+    PRICES = {
+      "openai" => {
+        # Source: https://developers.openai.com/api/docs/pricing
+        "gpt-5.3-codex" => { input: 1.75, cached_input: 0.175, output: 14.00, as_of: "2026-08-02" },
+        # Short-context service-tier rates read 2026-08-03. Long-context
+        # rates are deliberately absent until exact source pricing is known.
+        "gpt-5.5" => {
+          max_context_tokens_exclusive: 272_000,
+          service_tier_aliases: { "priority" => "fast" }.freeze,
+          service_tiers: {
+            "standard" => { input: 5.00, cached_input: 0.50, output: 30.00, as_of: "2026-08-03" },
+            "flex" => { input: 2.50, cached_input: 0.25, output: 15.00, as_of: "2026-08-03" },
+            "fast" => { input: 12.50, cached_input: 1.25, output: 75.00, as_of: "2026-08-03" }
+          }.freeze
+        }.freeze,
+        "gpt-5.2" => { input: 1.75, cached_input: 0.175, output: 14.00, as_of: "2026-08-02" },
+        "gpt-5.1" => { input: 1.25, cached_input: 0.125, output: 10.00, as_of: "2026-08-02" },
+        "gpt-5" => { input: 1.25, cached_input: 0.125, output: 10.00, as_of: "2026-08-02" },
+        "gpt-5-mini" => { input: 0.25, cached_input: 0.025, output: 2.00, as_of: "2026-08-02" }
+      }.freeze,
+      "anthropic" => {
+        # Source: https://claude.com/platform/api (cache read = 0.1x input)
+        "claude-fable-5" => { input: 10.00, cached_input: 1.00, output: 50.00, as_of: "2026-08-02" },
+        "claude-opus-5" => { input: 5.00, cached_input: 0.50, output: 25.00, as_of: "2026-08-02" },
+        "claude-sonnet-5" => { input: 2.00, cached_input: 0.20, output: 10.00, as_of: "2026-08-02" },
+        "claude-haiku-4-5" => { input: 1.00, cached_input: 0.10, output: 5.00, as_of: "2026-08-02" }
+      }.freeze
+    }.freeze
+
+    module_function
+
+    # Returns { cost_usd:, as_of: } or nil when the cost cannot be computed
+    # (unknown provider/model/service tier, or input/output token counts missing).
+    def compute(provider:, model:, input_tokens:, output_tokens:, cached_tokens: nil,
+                service_tier: nil, context_tokens: nil,
+                input_includes_cached: false)
+      model_entry = PRICES.dig(provider.to_s, model.to_s)
+      return nil unless model_entry
+      return nil unless context_priceable?(model_entry, context_tokens)
+
+      entry = rates_for_service_tier(model_entry, service_tier)
+      return nil unless entry
+      return nil unless input_tokens.is_a?(Numeric) && output_tokens.is_a?(Numeric)
+
+      cached = cached_tokens.is_a?(Numeric) ? cached_tokens : 0
+      billable_input = input_includes_cached ? input_tokens - cached : input_tokens
+      billable_input = 0 if billable_input.negative?
+
+      cost = (billable_input * entry[:input] +
+              cached * entry[:cached_input] +
+              output_tokens * entry[:output]) / 1_000_000.0
+      { cost_usd: cost.round(6), as_of: entry[:as_of] }
+    end
+
+    def context_priceable?(entry, context_tokens)
+      limit = entry[:max_context_tokens_exclusive]
+      return true unless limit
+
+      context_tokens.is_a?(Numeric) && context_tokens >= 0 && context_tokens < limit
+    end
+
+    def rates_for_service_tier(entry, service_tier)
+      tiers = entry[:service_tiers]
+      return entry unless tiers
+
+      tier = service_tier.to_s
+      return nil if tier.empty?
+
+      aliases = entry[:service_tier_aliases] || {}
+      tiers[aliases.fetch(tier, tier)]
+    end
+  end
+end