okstra 0.163.2 → 0.165.0

package/runtime/python/okstra_token_usage/collect.py

@@ -22,7 +22,6 @@ from .antigravity import (
 from .paths import claude_project_dir, utc_now
 from .pricing import antigravity_cost_usd, provider_cost_usd
 from okstra_ctl.models import provider_wrappers
-from okstra_ctl.lead_runtime import ARTIFACT_ONLY_LEAD_RUNTIMES
 from okstra_ctl.wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
@@ -705,14 +704,17 @@ def _populate_usage_summary(
     workers = state.get("workers", [])
     lead = state.get("leadUsage") or {}
     lead_total = lead.get("totalTokens", 0) or 0
+    lead_cache_read = lead.get("cacheReadTokens", 0) or 0
     lead_billable = lead.get("billableEquivalentTokens", 0) or 0
     lead_cost = lead.get("estimatedCostUsd", 0) or 0
     worker_total = sum((w.get("usage") or {}).get("totalTokens", 0) or 0 for w in workers)
+    worker_cache_read = sum((w.get("usage") or {}).get("cacheReadTokens", 0) or 0 for w in workers)
     worker_billable = sum((w.get("usage") or {}).get("billableEquivalentTokens", 0) or 0 for w in workers)
     worker_cost = sum((w.get("usage") or {}).get("estimatedCostUsd", 0) or 0 for w in workers)
     cli_cost = sum((w.get("usage") or {}).get("cliEstimatedCostUsd", 0) or 0 for w in workers)
     if unattributed_usage is not None:
         worker_total += unattributed_usage.get("totalTokens", 0) or 0
+        worker_cache_read += unattributed_usage.get("cacheReadTokens", 0) or 0
         worker_billable += unattributed_usage.get("billableEquivalentTokens", 0) or 0
         worker_cost += unattributed_usage.get("estimatedCostUsd", 0) or 0
 
@@ -734,6 +736,9 @@ def _populate_usage_summary(
         "leadTotalTokens": lead_total,
         "workerTotalTokens": worker_total,
         "grandTotalTokens": lead_total + worker_total,
+        "leadCacheReadTokens": lead_cache_read,
+        "workerCacheReadTokens": worker_cache_read,
+        "grandCacheReadTokens": lead_cache_read + worker_cache_read,
         "leadBillableEquivalentTokens": lead_billable,
         "workerBillableEquivalentTokens": worker_billable,
         "grandBillableEquivalentTokens": lead_billable + worker_billable,
@@ -751,26 +756,28 @@ def _populate_usage_summary(
         "unattributedTeamSessions": unattributed_sessions or [],
         "unattributedWorkerUsage": unattributed_usage,
         "definitions": {
-            "totalTokens": "Sum of input + output + cache_creation + cache_read tokens (raw processed volume; matches Anthropic API breakdown). Cache reads are 95%+ in long sessions.",
+            "totalTokens": "Sum of input + output + cache_creation tokens — the volume the session put through the model once. cache_read is excluded and reported separately as cacheReadTokens: a session re-reads its whole context from cache every turn, so folding it in here would count the same tokens once per turn.",
+            "cacheReadTokens": "Context re-read from cache. Billed at 0.1x base input, so it lands in billableEquivalentTokens and in the cost even though it is not part of totalTokens.",
             "billableEquivalentTokens": "Tokens normalized to base-input-price units (cache_creation_5m x1.25, cache_creation_1h x2.0, cache_read x0.1, output x5). 5m vs 1h is split from usage.cache_creation when the API breakdown is present; otherwise all cache_creation falls into 5m.",
             "estimatedCostUsd": "USD cost using public list pricing for the model recorded in the session. cliWorkers covers attributable registered-provider CLI calls.",
         },
     }
 
 
-def collect(team_state_path: Path, project_root: Path | None = None, *,
-            incremental: bool = True) -> dict:
+def collect_claude_runtime_usage(
+    team_state_path: Path,
+    project_root: Path | None = None,
+    *,
+    incremental: bool = True,
+) -> dict:
     # incremental: 세션 jsonl 스캔에 byte cursor 캐시 사용 (P6). 캐시는 윈도우
     # 적용 전 이벤트를 저장하므로 결과는 전체 스캔과 동일 — False 는 캐시 경로를
     # 완전히 우회하는 정확성 폴백(CLI --no-cache).
     state = json.loads(team_state_path.read_text())
     cwd = project_root or _infer_project_root(team_state_path, state)
     run_since, run_until = resolve_run_window(team_state_path, state)
-    task_key = state.get("taskKey", "")
     team_name = resolve_team_name(state)
     lead_sid = (state.get("lead") or {}).get("sessionId")
-    if state.get("leadRuntime") in ARTIFACT_ONLY_LEAD_RUNTIMES:
-        return _collect_cli_runtime_usage(state, cwd)
 
     # 1) Claude sessions (lead + claude-side workers). Cache totals at scan
     # time so we don't re-read the jsonl when a worker matches multiple
@@ -936,6 +943,34 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
     return state
 
 
+def collect_cli_runtime_usage(
+    team_state_path: Path,
+    project_root: Path | None = None,
+    *,
+    incremental: bool = True,
+) -> dict:
+    state = json.loads(team_state_path.read_text())
+    cwd = project_root or _infer_project_root(team_state_path, state)
+    return _collect_cli_runtime_usage(state, cwd)
+
+
+def collect(
+    team_state_path: Path,
+    project_root: Path | None = None,
+    *,
+    incremental: bool = True,
+) -> dict:
+    from okstra_ctl.application.collect_usage import collect_usage
+    from okstra_ctl.ports.usage_accounting import UsageRequest
+    from okstra_ctl.registry.host_registry import default_host_registry
+
+    state = json.loads(team_state_path.read_text())
+    cwd = project_root or _infer_project_root(team_state_path, state)
+    adapter = default_host_registry().resolve(str(state.get("leadRuntime") or ""))
+    request = UsageRequest(team_state_path, cwd, incremental)
+    return collect_usage(request, adapter.usage_accounting()).payload
+
+
 def _infer_project_root(team_state_path: Path, state: dict) -> Path:
     rel = state.get("runDirectoryPath") or ""
     p = team_state_path.resolve().parent

package/runtime/python/okstra_token_usage/report.py

@@ -24,6 +24,8 @@ from okstra_ctl.render_final_report import (  # noqa: E402
     render_to_file,
 )
 
+from .task_totals import task_cumulative_usage  # noqa: E402
+
 
 class SubstituteRefusedError(RuntimeError):
     """Raised when substitution would write zero-only token cells.
@@ -89,6 +91,8 @@ def _populate_execution_row(row: dict, source: dict) -> None:
         return
     if "totalTokens" in usage:
         row["totalTokens"] = usage["totalTokens"]
+    if "cacheReadTokens" in usage:
+        row["cacheReadTokens"] = usage["cacheReadTokens"]
     if "billableEquivalentTokens" in usage:
         row["billableTokens"] = usage["billableEquivalentTokens"]
     if "estimatedCostUsd" in usage:
@@ -114,6 +118,7 @@ def _worker_detail_row(label: str, usage: dict) -> dict:
         return {
             "label": label,
             "totalTokens": None,
+            "cacheReadTokens": None,
             "billableTokens": None,
             "costUsd": None,
             "cliTotalTokens": None,
@@ -122,6 +127,7 @@ def _worker_detail_row(label: str, usage: dict) -> dict:
     return {
         "label": label,
         "totalTokens": usage.get("totalTokens"),
+        "cacheReadTokens": usage.get("cacheReadTokens"),
         "billableTokens": usage.get("billableEquivalentTokens"),
         "costUsd": usage.get("estimatedCostUsd"),
         "cliTotalTokens": usage.get("cliTotalTokens"),
@@ -129,6 +135,35 @@ def _worker_detail_row(label: str, usage: dict) -> dict:
     }
 
 
+def _cache_reads(summary: dict, team_state: dict) -> dict[str, int]:
+    """Lead / worker / grand cache-read totals for this run.
+
+    The figure joined `usageSummary` after most team-states on disk were
+    written, and re-rendering one of those reports is exactly when the reader
+    goes looking for the corrected table — so a state without the summary keys
+    is added up from the usage blocks it does carry.
+    """
+    lead = summary.get("leadCacheReadTokens")
+    worker = summary.get("workerCacheReadTokens")
+    if isinstance(lead, int) and isinstance(worker, int):
+        return {"lead": lead, "worker": worker, "grand": lead + worker}
+    lead = _cache_read_tokens(team_state.get("leadUsage"))
+    worker = sum(
+        _cache_read_tokens(entry.get("usage"))
+        for entry in team_state.get("workers") or []
+        if isinstance(entry, dict)
+    )
+    worker += _cache_read_tokens(summary.get("unattributedWorkerUsage"))
+    return {"lead": lead, "worker": worker, "grand": lead + worker}
+
+
+def _cache_read_tokens(usage: object) -> int:
+    if not isinstance(usage, dict):
+        return 0
+    value = usage.get("cacheReadTokens")
+    return value if isinstance(value, int) else 0
+
+
 def _worker_detail_rows(team_state: dict) -> list[dict]:
     rows = []
     for worker in team_state.get("workers") or []:
@@ -178,19 +213,23 @@ def populate_data_token_cells(data_path: Path, team_state: dict) -> int:
     worker_cost = cost.get("claudeWorkers") or 0
     cli_cost = cost.get("cliWorkers") or 0
 
+    cache_reads = _cache_reads(summary, team_state)
     token_usage = data.setdefault("tokenUsage", {})
     token_usage.setdefault("lead", {}).update({
         "totalTokens": summary.get("leadTotalTokens"),
+        "cacheReadTokens": cache_reads["lead"],
         "billableTokens": summary.get("leadBillableEquivalentTokens"),
         "costUsd": lead_cost,
     })
     token_usage.setdefault("worker", {}).update({
         "totalTokens": summary.get("workerTotalTokens"),
+        "cacheReadTokens": cache_reads["worker"],
         "billableTokens": summary.get("workerBillableEquivalentTokens"),
         "costUsd": worker_cost,
     })
     token_usage.setdefault("grand", {}).update({
         "totalTokens": summary.get("grandTotalTokens"),
+        "cacheReadTokens": cache_reads["grand"],
         "billableTokens": summary.get("grandBillableEquivalentTokens"),
         # CLI tracked on its own row per the template — grand here means
         # lead + claudeWorkers, not lead + claudeWorkers + cli.
@@ -198,6 +237,9 @@ def populate_data_token_cells(data_path: Path, team_state: dict) -> int:
     })
     token_usage.setdefault("cli", {})["costUsd"] = cli_cost
     token_usage["workerDetails"] = _worker_detail_rows(team_state)
+    cumulative = task_cumulative_usage(data_path)
+    if cumulative is not None:
+        token_usage["taskCumulative"] = cumulative
     changes += 4
 
     # Execution Status by Agent — per-row token / cost / duration.

package/runtime/python/okstra_token_usage/task_totals.py

@@ -0,0 +1,88 @@
+"""What a whole task has spent, across every run of every phase.
+
+A report's own figures cover one run, but a task reaches its plan through
+several: the first pass, a clarification re-run, a conformance fix. Each of
+those bills separately, and a reader who only ever sees the last one has no way
+to learn what the task cost. The per-run team-states are the only record of the
+earlier passes, so the total is summed from them here rather than carried
+forward inside any single run's state.
+
+Every team-state is read directly rather than through its `usageSummary`: the
+summary predates the cache-read figure, so an older run would drop out of that
+column while still counting in the others.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_TEAM_STATE_GLOB = "runs/*/state/team-state-*.json"
+_SUMMED_KEYS = (
+    ("totalTokens", "totalTokens"),
+    ("cacheReadTokens", "cacheReadTokens"),
+    ("billableTokens", "billableEquivalentTokens"),
+    ("costUsd", "estimatedCostUsd"),
+)
+
+
+def _task_root(data_path: Path) -> Path | None:
+    """The task-bundle directory a report lives under.
+
+    Report path shape: `<task-id>/runs/<task-type>/reports/<name>.data.json`.
+    A path that does not match is not inside a task bundle — a fixture under a
+    tmp dir, most often — and has no sibling runs to total.
+    """
+    parents = data_path.parents
+    if len(parents) < 4:
+        return None
+    if parents[0].name != "reports" or parents[2].name != "runs":
+        return None
+    return parents[3]
+
+
+def _usage_blocks(team_state: dict) -> list[dict]:
+    blocks = [team_state.get("leadUsage") or {}]
+    for worker in team_state.get("workers") or []:
+        if isinstance(worker, dict):
+            blocks.append(worker.get("usage") or {})
+    unattributed = (team_state.get("usageSummary") or {}).get("unattributedWorkerUsage")
+    if isinstance(unattributed, dict):
+        blocks.append(unattributed)
+    return [block for block in blocks if isinstance(block, dict)]
+
+
+def _number(value: object) -> int | float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return 0
+    return value
+
+
+def task_cumulative_usage(data_path: Path) -> dict | None:
+    """Sum every measured run of this report's task, or None when there is none.
+
+    A run whose collector found no session contributes zero tokens and is left
+    out of `runCount` — counting it would make the average per run look cheaper
+    than the runs that were actually measured.
+    """
+    root = _task_root(data_path)
+    if root is None:
+        return None
+    totals = {name: 0 for name, _ in _SUMMED_KEYS}
+    run_count = 0
+    for state_path in sorted(root.glob(_TEAM_STATE_GLOB)):
+        try:
+            team_state = json.loads(state_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        if not isinstance(team_state, dict):
+            continue
+        blocks = _usage_blocks(team_state)
+        measured = sum(_number(block.get("totalTokens")) for block in blocks)
+        if measured <= 0:
+            continue
+        run_count += 1
+        for name, source_key in _SUMMED_KEYS:
+            totals[name] += sum(_number(block.get(source_key)) for block in blocks)
+    if not run_count:
+        return None
+    return {**totals, "runCount": run_count}