pennyrouter 0.3.19 → 0.3.21

package/standalone/penny-compare

@@ -0,0 +1,318 @@
+#!/usr/bin/env bash
+# Opens two harness sessions side by side, each with a live token readout.
+#
+#   penny-compare                                     menu
+#   penny-compare claude penny-claude                 launch directly
+#   penny-compare --model opus claude penny-claude    both panes on one model
+#   penny-compare --dir-left ~/a --dir-right ~/b claude penny-claude
+#                                                      each pane in its own directory
+#   penny-compare --native-proxy claude penny-claude  NATIVE pane routes through
+#                                                      PENNY_COMPARE_NATIVE_BASE_URL /
+#                                                      PENNY_COMPARE_NATIVE_AUTH_TOKEN
+#   penny-compare --wire codex penny-codex            capture the NATIVE pane's wire body
+#                                                      through a local intercepting proxy
+#   penny-compare --wire-both codex penny-codex       also capture the gateway's raw ingress
+#   penny-compare --wire-https codex penny-codex      force the HTTPS fallback shape instead
+#                                                      of the WebSocket frame
+#   penny-compare --label-left gpt5 --label-right penny claude penny-claude
+#                                                      rename each readout
+#
+# Without --native-proxy the NATIVE pane always talks to Anthropic directly, whatever the
+# surrounding shell exports.
+#
+# Input is broadcast to both panes by default. Each key has a prefix spelling for terminals
+# that cannot send ctrl-shift combinations (Terminal.app among them).
+#   ctrl-shift-s / ctrl-b s        sync on/off
+#   ctrl-left    / ctrl-b left     focus the left pane
+#   ctrl-right   / ctrl-b right    focus the right pane
+#   ctrl-shift-r / ctrl-b r        zero the counters (after warming both caches)
+#   ctrl-shift-x / ctrl-b x        save report, show savings, then Enter to quit
+set -euo pipefail
+
+# Resolve through a symlink so the launcher works when linked onto PATH; the helper scripts
+# live beside the real file, not beside the link.
+source="${BASH_SOURCE[0]}"
+while [ -L "$source" ]; do
+  dir="$(cd -P "$(dirname "$source")" && pwd)"
+  source="$(readlink "$source")"
+  [[ "$source" != /* ]] && source="$dir/$source"
+done
+here="$(cd -P "$(dirname "$source")" && pwd)"
+session="penny-compare-$$"
+state="$(mktemp -d)"
+trap 'rm -rf "$state"' EXIT
+
+# Optional local settings, kept beside this script and out of git (see .env.example).
+# Values already exported in the shell win, so a one-off run can override the file.
+if [ -f "$here/.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  source "$here/.env"
+  set +a
+fi
+
+variants=(claude penny-claude codex penny-codex opencode penny-opencode)
+
+model=""
+dir_left=""
+dir_right=""
+native_proxy=""
+label_left=""
+label_right=""
+wire=""
+wire_both=""
+wire_https=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --model) model="$2"; shift 2 ;;
+    --dir-left) dir_left="$2"; shift 2 ;;
+    --dir-right) dir_right="$2"; shift 2 ;;
+    --native-proxy) native_proxy="--native-proxy"; shift ;;
+    --label-left) label_left="$2"; shift 2 ;;
+    --label-right) label_right="$2"; shift 2 ;;
+    --wire) wire="--wire"; shift ;;
+    --wire-both) wire="--wire"; wire_both="--wire-both"; shift ;;
+    --wire-https) wire="--wire"; wire_https="--wire-https"; shift ;;
+    *) break ;;
+  esac
+done
+
+# Offer a numbered list and accept either a number, a typed value, or the default.
+choose() {
+  local prompt="$1" default="$2"; shift 2
+  local options=("$@") reply index=1
+  echo "  $prompt" >&2
+  for option in "${options[@]}"; do
+    printf '    %d) %s\n' "$index" "$option" >&2
+    index=$((index + 1))
+  done
+  read -r -p "  [$default] " reply >&2 || true
+  if [ -z "$reply" ]; then echo "$default"; return; fi
+  if [[ "$reply" =~ ^[0-9]+$ ]] && [ "$reply" -ge 1 ] && [ "$reply" -le "${#options[@]}" ]; then
+    echo "${options[$((reply - 1))]}"
+    return
+  fi
+  echo "$reply"
+}
+
+# Aliases Claude Code resolves on both the native and the penny side, so a comparison stays like
+# for like. A full model id (claude-opus-5) works too.
+claude_models=(default opus sonnet haiku fable)
+
+# The current Codex catalog (apps/gateway/pennyrouter/main.py, _CODEX_NATIVE_MODELS), newest
+# first. That tuple also carries three PennyRouter-only aliases (gpt-penny-deepseek/glm/grok)
+# that route to other providers entirely; those are left out here since a native Codex pane would
+# reject them, making an "identical model on both sides" comparison impossible.
+codex_models=(default gpt-5.6-sol gpt-5.6-terra gpt-5.6-luna gpt-5.5 gpt-5.4 gpt-5.4-mini)
+
+# OpenCode's configured default is the only portable alias; users can pass a full
+# provider/model id with --model when both panes must use a specific model.
+opencode_models=(default)
+
+if [ $# -ge 2 ]; then
+  left="$1"; right="$2"
+else
+  echo >&2
+  echo "  penny-compare" >&2
+  echo >&2
+  left="$(choose 'left pane' claude "${variants[@]}")"
+  echo >&2
+  if [ -z "$dir_left" ]; then
+    echo "  left directory  (blank = $PWD)" >&2
+    read -r -p "  [] " dir_left >&2 || true
+    echo >&2
+  fi
+  if [ -z "$label_left" ]; then
+    echo "  left label      (blank = NATIVE or PENNY)" >&2
+    read -r -p "  [] " label_left >&2 || true
+    echo >&2
+  fi
+  right="$(choose 'right pane' penny-claude "${variants[@]}")"
+  echo >&2
+  if [ -z "$dir_right" ]; then
+    echo "  right directory (blank = $PWD)" >&2
+    read -r -p "  [] " dir_right >&2 || true
+    echo >&2
+  fi
+  if [ -z "$label_right" ]; then
+    echo "  right label     (blank = NATIVE or PENNY)" >&2
+    read -r -p "  [] " label_right >&2 || true
+    echo >&2
+  fi
+  if [ -z "$model" ]; then
+    case "$left $right" in
+      *codex*claude*|*claude*codex*)
+        # No model name means the same thing on both a Claude and a Codex pane.
+        ;;
+      *codex*)
+        model="$(choose 'model  (both panes)' default "${codex_models[@]}")"
+        [ "$model" = "default" ] && model=""
+        echo >&2
+        ;;
+      *opencode*)
+        model="$(choose 'model  (both panes)' default "${opencode_models[@]}")"
+        [ "$model" = "default" ] && model=""
+        echo >&2
+        ;;
+      *)
+        model="$(choose 'model  (both panes)' default "${claude_models[@]}")"
+        [ "$model" = "default" ] && model=""
+        echo >&2
+        ;;
+    esac
+  fi
+  # Only meaningful when a NATIVE pane (exactly "claude" or "codex") is actually in
+  # play; a penny-* pane already owns its own proxy routing regardless of this answer.
+  has_native_pane=""
+  case "$left" in claude|codex) has_native_pane=1 ;; esac
+  case "$right" in claude|codex) has_native_pane=1 ;; esac
+  if [ -z "$native_proxy" ] && [ -n "$has_native_pane" ]; then
+    read -r -p "  Use Proxy? (y/N) " native_proxy_choice >&2 || true
+    case "$native_proxy_choice" in
+      [yY]|[yY][eE][sS]) native_proxy="--native-proxy" ;;
+    esac
+    echo >&2
+  fi
+fi
+
+# A directory that does not exist would otherwise surface as a confusing tmux failure.
+for candidate in "$dir_left" "$dir_right"; do
+  if [ -n "$candidate" ] && [ ! -d "${candidate/#\~/$HOME}" ]; then
+    echo "no such directory: $candidate" >&2
+    exit 1
+  fi
+done
+
+if [ -n "$model" ]; then
+  case "$left $right" in
+    *codex*) known=("${codex_models[@]}") ;;
+    *) known=("${claude_models[@]}") ;;
+  esac
+  case " ${known[*]} " in
+    *" $model "*) ;;
+    *)
+      case "$left $right" in
+        *codex*)
+          # The Codex catalog above is exact, so anything outside it is a typo or one of the
+          # penny-only aliases (gpt-penny-*) that a native pane cannot use.
+          echo "unknown model: $model (try ${known[*]})" >&2; exit 1 ;;
+        *opencode*)
+          # OpenCode model ids are provider-specific and come from the user's config.
+          ;;
+        *)
+          # Claude has dated snapshots (claude-opus-5-20260315) that are valid but not aliased
+          # above; only reject something that is clearly not a Claude model id at all.
+          case "$model" in
+            claude-*) ;;
+            *) echo "unknown model: $model (try ${known[*]}, or a full model id)" >&2; exit 1 ;;
+          esac
+          ;;
+      esac
+      ;;
+  esac
+fi
+
+for variant in "$left" "$right"; do
+  case " ${variants[*]} " in
+    *" $variant "*) ;;
+    *) echo "unknown variant: $variant" >&2; exit 1 ;;
+  esac
+done
+
+if ! command -v tmux >/dev/null; then
+  echo "penny-compare needs tmux" >&2
+  exit 1
+fi
+
+delta="$state/delta.txt"
+: > "$delta"
+: > "$state/started"
+
+export PENNY_COMPARE_STATE="$state"
+
+# Each pane's readout finds its session by the directory it ran in, so the two must be set
+# explicitly rather than left to tmux's default of wherever the launcher was invoked.
+workdir_left="${dir_left:-$PWD}"
+workdir_left="${workdir_left/#\~/$HOME}"
+workdir_right="${dir_right:-$PWD}"
+workdir_right="${workdir_right/#\~/$HOME}"
+
+# --native-proxy only means anything on a NATIVE Claude or Codex pane;
+# a penny-* pane already owns its own proxy routing and ignores the flag either way.
+native_proxy_left=""
+native_proxy_right=""
+pricing_profile="standard"
+if [ -n "$native_proxy" ]; then
+  pricing_profile="govcloud"
+  case "$left" in claude|codex) native_proxy_left="$native_proxy" ;; esac
+  case "$right" in claude|codex) native_proxy_right="$native_proxy" ;; esac
+fi
+
+# A label is free text, so it reaches the pane as a single quoted word rather than being
+# split by the shell tmux runs the command string through.
+label_left_arg=""
+label_right_arg=""
+if [ -n "$label_left" ]; then
+  label_left_arg=" --label $(printf '%q' "$label_left")"
+fi
+if [ -n "$label_right" ]; then
+  label_right_arg=" --label $(printf '%q' "$label_right")"
+fi
+
+# Wire flags reach both panes; pane.py decides what each role does with them, so a capture
+# follows the NATIVE pane whichever side it was launched on.
+wire_args="${wire:+ $wire}${wire_both:+ $wire_both}${wire_https:+ $wire_https}"
+
+tmux new-session -d -s "$session" -c "$workdir_left" -x "$(tput cols)" -y "$(tput lines)" \
+  -e PENNY_COMPARE_STATE="$state" \
+  "$here/pane.py $left --side left --pricing-profile $pricing_profile${model:+ --model $model}${native_proxy_left:+ $native_proxy_left}${label_left_arg}${wire_args}"
+tmux split-window -h -t "$session" -c "$workdir_right" \
+  -e PENNY_COMPARE_STATE="$state" \
+  "$here/pane.py $right --side right --pricing-profile $pricing_profile --delta-file $delta${model:+ --model $model}${native_proxy_right:+ $native_proxy_right}${label_right_arg}${wire_args}"
+
+# The comparison belongs to neither pane, so a small watcher derives it from both.
+tmux new-window -d -t "$session" -n delta "$here/delta.py '$state' '$delta'"
+
+# Ctrl-shift keys reach tmux only when the terminal reports them as distinct sequences.
+tmux set-option -t "$session" -g extended-keys on
+tmux set-option -t "$session" -g mouse on
+tmux set-option -t "$session" -g status-position top
+tmux set-option -t "$session" -g status-style "bg=colour234,fg=colour46"
+tmux set-option -t "$session" -g status-left ""
+tmux set-option -t "$session" -g status-right ""
+tmux set-option -t "$session" -g status-justify centre
+tmux set-window-option -t "$session" -g window-status-format ""
+tmux set-window-option -t "$session" -g window-status-current-format \
+  "  #{?pane_synchronized,#[bold]SYNC ON,#[fg=colour242]sync off}#[default]   sync ^⇧S/^b s · focus ^←→/^b ←→ · reset ^⇧R/^b r · quit ^⇧X/^b x  "
+
+# One input box, both panes.
+tmux set-window-option -t "$session" synchronize-panes on
+
+# Direct keys, no prefix. Focusing a single pane turns sync off, since typing into one pane
+# while both receive input is the surprising case.
+tmux bind-key -n C-S-s set-window-option synchronize-panes \; \
+  display-message "sync #{?pane_synchronized,on,off}"
+tmux bind-key -n C-Left select-pane -t 0 \; set-window-option synchronize-panes off \; \
+  display-message "left pane · sync off"
+tmux bind-key -n C-Right select-pane -t 1 \; set-window-option synchronize-panes off \; \
+  display-message "right pane · sync off"
+tmux bind-key -n C-S-x new-window -t "$session" -n report \
+  "$here/report.py '$state' '$here/reports' '$session'"
+# Zero both readouts without restarting either session. A comparison is only fair once both
+# sides have a warm cache, so the run that counts is rarely the first one.
+tmux bind-key -n C-S-r run-shell "touch '$state/reset'" \; display-message "counters reset"
+
+# Terminals that do not implement the Kitty keyboard protocol (Terminal.app among them) cannot
+# send ctrl-shift keys as distinct sequences, so every direct key also has a prefix spelling.
+tmux bind-key s set-window-option synchronize-panes \; \
+  display-message "sync #{?pane_synchronized,on,off}"
+tmux bind-key Left select-pane -t 0 \; set-window-option synchronize-panes off \; \
+  display-message "left pane · sync off"
+tmux bind-key Right select-pane -t 1 \; set-window-option synchronize-panes off \; \
+  display-message "right pane · sync off"
+tmux bind-key r run-shell "touch '$state/reset'" \; display-message "counters reset"
+tmux bind-key x new-window -t "$session" -n report \
+  "$here/report.py '$state' '$here/reports' '$session'"
+
+tmux select-pane -t "$session":0.0
+exec tmux attach-session -t "$session"

package/standalone/penny-compare-viewer

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source="${BASH_SOURCE[0]}"
+while [ -L "$source" ]; do
+  dir="$(cd -P "$(dirname "$source")" && pwd)"
+  source="$(readlink "$source")"
+  [[ "$source" != /* ]] && source="$dir/$source"
+done
+here="$(cd -P "$(dirname "$source")" && pwd)"
+exec python3 "$here/viewer.py" "$@"

package/standalone/penny-session

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Run one ordinary Claude Code or Codex session with Penny Compare's live HUD.
+#
+#   penny-session                         Penny-routed Claude Code
+#   penny-session penny-codex             Penny-routed Codex
+#   penny-session penny-opencode          Penny-routed OpenCode
+#   penny-session claude --model sonnet   native Claude Code
+#
+set -euo pipefail
+
+source="${BASH_SOURCE[0]}"
+while [ -L "$source" ]; do
+  dir="$(cd -P "$(dirname "$source")" && pwd)"
+  source="$(readlink "$source")"
+  [[ "$source" != /* ]] && source="$dir/$source"
+done
+here="$(cd -P "$(dirname "$source")" && pwd)"
+
+if [ -f "$here/.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  source "$here/.env"
+  set +a
+fi
+
+variant="penny-claude"
+if [ $# -gt 0 ] && [[ "$1" != -* ]]; then
+  variant="$1"
+  shift
+fi
+
+case "$variant" in
+  claude|penny-claude|codex|penny-codex|opencode|penny-opencode) ;;
+  *)
+    echo "unknown variant: $variant (try claude, penny-claude, codex, penny-codex, opencode, or penny-opencode)" >&2
+    exit 1
+    ;;
+esac
+
+workdir=""
+label=""
+pricing_profile="standard"
+native_proxy=""
+model=""
+wire=""
+wire_https=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dir)
+      [ $# -ge 2 ] || { echo "--dir needs a directory" >&2; exit 2; }
+      workdir="$2"; shift 2
+      ;;
+    --label)
+      [ $# -ge 2 ] || { echo "--label needs a name" >&2; exit 2; }
+      label="$2"; shift 2
+      ;;
+    --model)
+      [ $# -ge 2 ] || { echo "--model needs a model" >&2; exit 2; }
+      model="$2"; shift 2
+      ;;
+    --pricing-profile)
+      [ $# -ge 2 ] || { echo "--pricing-profile needs standard or govcloud" >&2; exit 2; }
+      pricing_profile="$2"; shift 2
+      ;;
+    --native-proxy) native_proxy="--native-proxy"; shift ;;
+    --wire) wire="--wire"; shift ;;
+    --wire-https) wire="--wire"; wire_https="--wire-https"; shift ;;
+    -h|--help)
+      sed -n '2,8p' "$source"
+      echo
+      echo "Options: --dir PATH  --label NAME  --model MODEL  --pricing-profile PROFILE  --native-proxy"
+      echo "         --wire  --wire-https"
+      exit 0
+      ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -n "$workdir" ]; then
+  workdir="${workdir/#\~/$HOME}"
+  [ -d "$workdir" ] || { echo "no such directory: $workdir" >&2; exit 1; }
+  cd "$workdir"
+fi
+
+case "$pricing_profile" in
+  standard|govcloud) ;;
+  *) echo "unknown pricing profile: $pricing_profile" >&2; exit 1 ;;
+esac
+
+args=("$here/pane.py" "$variant" --side single --pricing-profile "$pricing_profile")
+[ -n "$model" ] && args+=(--model "$model")
+[ -n "$label" ] && args+=(--label "$label")
+[ -n "$native_proxy" ] && args+=("$native_proxy")
+if [ -n "$wire" ]; then
+  args+=("$wire")
+  [ -n "$wire_https" ] && args+=("$wire_https")
+  # pane.py splits capture by role: a NATIVE pane proxies its own traffic, a PENNY pane has
+  # the gateway write what its client sent. One session is only ever one of the two, so the
+  # PENNY form is selected here rather than asked for.
+  case "$variant" in penny-*) args+=(--wire-both) ;; esac
+fi
+
+exec python3 "${args[@]}"

package/standalone/pricing.py

@@ -0,0 +1,139 @@
+"""Per-token rates for the models the compare HUD reports on.
+
+Rates are USD per token. Anthropic prices a 5-minute cache write at 1.25x the base input rate
+and a 1-hour cache write at 2x; folding those into one "write" rate would misprice any session
+that uses 1-hour caching, which the gateway does by default.
+"""
+
+from __future__ import annotations
+
+# input, cache_read, write_5m, write_1h, output
+RATES = {
+    "claude-opus-5":     (5.00e-06, 5.00e-07, 6.25e-06, 1.00e-05, 2.50e-05),
+    "claude-sonnet-5":   (3.00e-06, 3.00e-07, 3.75e-06, 6.00e-06, 1.50e-05),
+    "claude-haiku-4-5":  (1.00e-06, 1.00e-07, 1.25e-06, 2.00e-06, 5.00e-06),
+    # OpenAI does not offer a 1-hour cache tier; its write rate applies uniformly.
+    "gpt-5-codex":       (1.25e-06, 1.25e-07, 1.25e-06, 1.25e-06, 1.00e-05),
+    "gpt-5.1-codex":     (1.25e-06, 1.25e-07, 1.25e-06, 1.25e-06, 1.00e-05),
+}
+
+# --native-proxy means the comparison is measuring the GovCloud route. Pricing remains the
+# same on both panes, but both use this schedule instead of the standard one.
+GOVCLOUD_RATES = {
+    "claude-opus-5":     (5.50e-06, 5.50e-07, 6.875e-06, 1.10e-05, 2.75e-05),
+    "claude-opus-4-8":   (5.50e-06, 5.50e-07, 6.875e-06, 1.10e-05, 2.75e-05),
+    "claude-sonnet-5":   (2.20e-06, 2.20e-07, 2.75e-06, 4.40e-06, 1.10e-05),
+    "claude-haiku-4-5":  (1.10e-06, 1.10e-07, 1.375e-06, 2.20e-06, 5.50e-06),
+}
+
+# GPT GovCloud pricing changes when an individual request's input context exceeds 272K.
+# Each entry is (inclusive threshold, <= threshold rates, > threshold rates), with rate tuples
+# in the same input/read/write-5m/write-1h/output order as RATES.
+GOVCLOUD_TIERED_RATES = {
+    "gpt-5.6-luna": (
+        272_000,
+        (0.22e-06, 0.022e-06, 0.275e-06, 0.275e-06, 1.32e-06),
+        (0.44e-06, 0.044e-06, 0.55e-06, 0.55e-06, 1.98e-06),
+    ),
+    "gpt-5.6-terra": (
+        272_000,
+        (2.20e-06, 0.22e-06, 2.75e-06, 2.75e-06, 13.20e-06),
+        (4.40e-06, 0.44e-06, 5.50e-06, 5.50e-06, 19.80e-06),
+    ),
+    "gpt-5.6-sol": (
+        272_000,
+        (4.40e-06, 0.44e-06, 5.50e-06, 5.50e-06, 22.00e-06),
+        (8.80e-06, 0.88e-06, 11.00e-06, 11.00e-06, 33.00e-06),
+    ),
+}
+
+CONTEXT_WINDOWS = {
+    "claude-opus-5": 200_000,
+    "claude-opus-4-8": 200_000,
+    "claude-sonnet-5": 200_000,
+    "claude-haiku-4-5": 200_000,
+    "gpt-5-codex": 272_000,
+    "gpt-5.1-codex": 272_000,
+}
+
+_FALLBACK = RATES["claude-sonnet-5"]
+
+
+def _normalize(model: str) -> str:
+    """Strip the vendor prefixes and long-context suffixes that wrap a base model id."""
+    name = (model or "").split("/")[-1].strip()
+    # Bedrock's Converse transcript ids retain Anthropic's provider namespace, e.g.
+    # ``converse/anthropic.claude-opus-5``.  Strip it before matching the shared model
+    # pricing tables; otherwise the lookup silently falls back to Sonnet pricing.
+    if name.startswith("anthropic."):
+        name = name[len("anthropic."):]
+    name = name.replace("[1m]", "").strip()
+    # Anthropic's upstream ids use dotted minor versions in a few places while Claude and the
+    # gateway can record the equivalent dashed id. Keep GPT's dotted generation names intact.
+    return {
+        "claude-opus-4.8": "claude-opus-4-8",
+        "claude-haiku-4.5": "claude-haiku-4-5",
+    }.get(name, name)
+
+
+def _matching(name: str, choices) -> str | None:
+    if name in choices:
+        return name
+    matches = [key for key in choices if name.startswith(key)]
+    return max(matches, key=len) if matches else None
+
+
+def rates_for(model: str, profile: str = "standard", context_tokens: int = 0):
+    name = _normalize(model)
+    if profile == "govcloud":
+        tiered = _matching(name, GOVCLOUD_TIERED_RATES)
+        if tiered:
+            threshold, low, high = GOVCLOUD_TIERED_RATES[tiered]
+            return high if context_tokens > threshold else low
+    rates = GOVCLOUD_RATES if profile == "govcloud" else RATES
+    match = _matching(name, rates)
+    if match:
+        return rates[match]
+    # Until a GovCloud override is supplied for a model, retain its standard model-specific
+    # rate rather than falling all the way back to Sonnet.
+    if profile == "govcloud":
+        return rates_for(model, "standard")
+    return _FALLBACK
+
+
+def context_window(model: str):
+    name = _normalize(model)
+    if "[1m]" in (model or ""):
+        return 1_000_000
+    if name in CONTEXT_WINDOWS:
+        return CONTEXT_WINDOWS[name]
+    matches = [k for k in CONTEXT_WINDOWS if name.startswith(k)]
+    if matches:
+        return CONTEXT_WINDOWS[max(matches, key=len)]
+    return None
+
+
+# The window sizes a session can actually be running at, smallest first.
+_WINDOW_TIERS = (200_000, 500_000, 1_000_000)
+
+
+def next_window_above(observed: int):
+    """The smallest real window that fits an observed context size."""
+    for tier in _WINDOW_TIERS:
+        if observed <= tier:
+            return tier
+    return observed
+
+
+def cost(model: str, fresh_input: int, cache_read: int, output: int,
+         write_5m: int = 0, write_1h: int = 0, profile: str = "standard",
+         context_tokens: int | None = None) -> float:
+    """Total cost for a turn's usage. `write_5m`/`write_1h` are the ephemeral cache-creation
+    buckets Anthropic reports separately, since the 1-hour tier is priced at 2x input rather
+    than the 5-minute tier's 1.25x. A caller with only a combined write figure and no split
+    (Codex, which has no 1-hour tier) should pass it as `write_5m`."""
+    if context_tokens is None:
+        context_tokens = fresh_input + cache_read + write_5m + write_1h
+    inp, read, w5, w1, out = rates_for(model, profile, context_tokens)
+    return (fresh_input * inp + cache_read * read
+            + write_5m * w5 + write_1h * w1 + output * out)