cctally 1.82.1 → 1.83.0

package/bin/_lib_conversation_query.py

@@ -21,7 +21,7 @@ from datetime import datetime as _datetime, timezone as _timezone
 # Public surface (Plan 2): shipped in the npm tarball + brew formula + public
 # mirror — imported by the dashboard's conversation endpoints at runtime.
 
-from _lib_pricing import _calculate_entry_cost, _chip_for_model
+from _lib_pricing import _calculate_entry_cost, _chip_for_model, claude_usage_dict
 # #178: the on-demand load-full re-read helper re-stringifies a raw tool_result
 # content block the same way the parser does at ingest — reuse the parser's
 # _stringify so the full (un-capped) result text matches the cached/capped one.
@@ -546,16 +546,22 @@ def _iso_ms(ts):
         return None
 
 
-def _entry_cost(model, inp, out, cc, cr, cost_usd_raw) -> float:
+def _entry_cost(
+    model, inp, out, cc, cr, cost_usd_raw, *, cc_1h, speed
+) -> float:
     """Cost for one session_entries row via the shared pricing helper. Tokens →
     the helper's usage dict. cost_usd_raw is passed as the optional override the
-    helper already understands (it is often NULL — never the primary source)."""
-    usage = {
-        "input_tokens": inp or 0,
-        "output_tokens": out or 0,
-        "cache_creation_input_tokens": cc or 0,
-        "cache_read_input_tokens": cr or 0,
-    }
+    helper already understands (it is often NULL — never the primary source).
+
+    `cc_1h` (#195) is a REQUIRED keyword, inherited verbatim from
+    `claude_usage_dict`: this is a thin shim over the builder, so a default here
+    would re-open the exact hazard the builder's required keyword closes — a
+    caller that forgets the split does not raise, it silently prices every
+    1-hour cache write at the 5-minute rate. Pass an explicit None for a
+    genuinely unknown split; that reads as a declaration at the call site."""
+    usage = claude_usage_dict(
+        input_tokens=inp, output_tokens=out, cache_creation_tokens=cc,
+        cache_read_tokens=cr, cache_1h_tokens=cc_1h, speed=speed)
     return _calculate_entry_cost(model or "", usage, cost_usd=cost_usd_raw)
 
 
@@ -576,26 +582,49 @@ _CACHE_FAILURE_CACHE_FLOOR = 20_000      # prior cache must be meaningful to "lo
 _CACHE_FAILURE_CREATE_FLOOR = 20_000     # the re-creation must be substantial / real cost
 
 
-def _cache_failure_wasted_usd(model, lost):
+def _cache_failure_wasted_usd(model, lost, *, speed):
     """Marginal extra paid by re-creating `lost` previously-cached tokens at the
     cache-WRITE rate instead of reading them at the cache-READ rate. Reuses the
     pricing chokepoint `_calculate_entry_cost` (zero on unknown models — the
     helper emits its own one-shot stderr warning, never raises). NEVER summed into
-    any cost-snapshot / budget / reconciled figure — a display-only estimate."""
-    write = _calculate_entry_cost(model or "", {"cache_creation_input_tokens": lost})
-    read = _calculate_entry_cost(model or "", {"cache_read_input_tokens": lost})
+    any cost-snapshot / budget / reconciled figure — a display-only estimate.
+    The lost-prefix subset has no authoritative mapping to the source row's
+    5m/1h write buckets, so this preserves the existing 5m estimate while
+    applying the retained effective speed tier."""
+    write = _calculate_entry_cost(
+        model or "",
+        claude_usage_dict(
+            cache_1h_tokens=None, speed=speed, cache_creation_tokens=lost
+        ),
+    )
+    read = _calculate_entry_cost(
+        model or "",
+        claude_usage_dict(
+            cache_1h_tokens=None, speed=speed, cache_read_tokens=lost
+        ),
+    )
     return write - read
 
 
-def _cache_read_saved_usd(model, cache_read):
+def _cache_read_saved_usd(model, cache_read, *, speed):
     """Marginal USD the cache SAVED this turn: the `cache_read` prefix priced at
     the full input rate minus its actual cache-READ rate. Display-only (same
     caveat as `_cache_failure_wasted_usd`): NEVER summed into a cost-snapshot /
     budget / reconciled figure. `input_tokens` and `cache_read_input_tokens` are
     independent keys in the Claude `_calculate_entry_cost` (no subset
     subtraction), so passing each alone yields the two rates cleanly."""
-    full = _calculate_entry_cost(model or "", {"input_tokens": cache_read})
-    read = _calculate_entry_cost(model or "", {"cache_read_input_tokens": cache_read})
+    full = _calculate_entry_cost(
+        model or "",
+        claude_usage_dict(
+            cache_1h_tokens=None, speed=speed, input_tokens=cache_read
+        ),
+    )
+    read = _calculate_entry_cost(
+        model or "",
+        claude_usage_dict(
+            cache_1h_tokens=None, speed=speed, cache_read_tokens=cache_read
+        ),
+    )
     return full - read
 
 
@@ -606,21 +635,24 @@ def _cache_read_saved_usd(model, cache_read):
 # a document-ordered list of these and feed it to the ONE predicate below — the
 # rule is implemented exactly once (U1, #217 S1).
 class _CFEvent:
-    __slots__ = ("compaction", "key", "cc", "cr", "model")
+    __slots__ = ("compaction", "key", "cc", "cr", "model", "speed")
 
-    def __init__(self, *, compaction=False, key=None, cc=0, cr=0, model=None):
+    def __init__(
+        self, *, compaction=False, key=None, cc=0, cr=0, model=None, speed=None
+    ):
         self.compaction = compaction
         self.key = key
         self.cc = cc
         self.cr = cr
         self.model = model
+        self.speed = speed
 
 
 def _iter_cache_failures(events):
     """The single cache-failure rule (spec §1), as a generator over a
     document-ordered ``_CFEvent`` stream. Yields ``(index, prev_cached, lost,
-    model)`` for each FLAGGED assistant event — ``index`` is the event's position
-    in ``events`` so a caller can map a flag back to its source item.
+    model, speed)`` for each FLAGGED assistant event — ``index`` is the event's
+    position in ``events`` so a caller can map a flag back to its source item.
 
     Maintains a running-max of ``cache_read`` keyed by the event's ``key``
     (``(subagent_key, model)`` — ``None`` subagent_key = main session). The key
@@ -660,7 +692,7 @@ def _iter_cache_failures(events):
                 and total > 0
                 and cc / total >= _CACHE_FAILURE_RECREATE_FRACTION):
             lost = min(cc, max(0, rm - cr))
-            yield (i, rm, lost, ev.model)
+            yield (i, rm, lost, ev.model, ev.speed)
         running_max[ev.key] = max(rm, cr)
 
 
@@ -695,7 +727,8 @@ def _cache_failure_events_from_items(items):
             key=(it.get("subagent_key"), it.get("model")),
             cc=tok.get("cache_creation", 0) or 0,
             cr=tok.get("cache_read", 0) or 0,
-            model=it.get("model")))
+            model=it.get("model"),
+            speed=it.get("_speed")))
         sources.append(it)
     return events, sources
 
@@ -719,11 +752,13 @@ def _stamp_cache_failures(items):
         est_wasted_usd   = write(lost) - read(lost)
     """
     events, sources = _cache_failure_events_from_items(items)
-    for idx, prev_cached, lost, model in _iter_cache_failures(events):
+    for idx, prev_cached, lost, model, speed in _iter_cache_failures(events):
         sources[idx]["cache_failure"] = {
             "tokens_recreated": lost,
             "prev_cached": prev_cached,
-            "est_wasted_usd": _cache_failure_wasted_usd(model, lost),
+            "est_wasted_usd": _cache_failure_wasted_usd(
+                model, lost, speed=speed
+            ),
         }
 
 
@@ -901,10 +936,15 @@ def _turn_costs_for_keys(conn, keys):
         cond = " OR ".join("(msg_id=? AND req_id=?)" for _ in chunk)
         params = [v for pair in chunk for v in pair]
         sql = ("SELECT msg_id, req_id, model, input_tokens, output_tokens, "
-               "cache_create_tokens, cache_read_tokens, cost_usd_raw "
+               "cache_create_tokens, cache_read_tokens, cost_usd_raw, "
+               "cache_create_1h_tokens, speed "
                "FROM session_entries WHERE " + cond)
-        for m, r, model, inp, out, cc, cr, raw in conn.execute(sql, params):
-            costs[(m, r)] = _entry_cost(model, inp, out, cc, cr, raw)
+        for m, r, model, inp, out, cc, cr, raw, cc1h, speed in conn.execute(
+            sql, params
+        ):
+            costs[(m, r)] = _entry_cost(
+                model, inp, out, cc, cr, raw, cc_1h=cc1h, speed=speed
+            )
     return costs
 
 
@@ -1539,7 +1579,7 @@ def _turn_cost_map(conn, turn_keys):
 
 
 def _turn_usage_map(conn, turn_keys):
-    """{(msg_id, req_id): {"input","output","cache_creation","cache_read"}} for
+    """{(msg_id, req_id): {tokens..., "speed"}} for
     the given non-null turn keys, read from the SAME deduped session_entries row
     cost is computed from (#177). This is a SEPARATE sibling of _turn_cost_map —
     that one returns a float and is also consumed by the search path
@@ -1557,11 +1597,12 @@ def _turn_usage_map(conn, turn_keys):
         cond = " OR ".join("(msg_id=? AND req_id=?)" for _ in chunk)
         params = [v for pair in chunk for v in pair]
         sql = ("SELECT msg_id, req_id, input_tokens, output_tokens, "
-               "cache_create_tokens, cache_read_tokens "
+               "cache_create_tokens, cache_read_tokens, speed "
                "FROM session_entries WHERE " + cond)
-        for m, r, inp, out, cc, cr in conn.execute(sql, params):
+        for m, r, inp, out, cc, cr, speed in conn.execute(sql, params):
             usage[(m, r)] = {"input": inp or 0, "output": out or 0,
-                             "cache_creation": cc or 0, "cache_read": cr or 0}
+                             "cache_creation": cc or 0, "cache_read": cr or 0,
+                             "speed": speed}
     return usage
 
 
@@ -1981,7 +2022,11 @@ def _assemble_session(conn, session_id):
             # key has no session_entries row (omitted, not zero-filled).
             tok = usage.get((it["_msg_id"], it["_req_id"]))
             if tok is not None:
-                it["tokens"] = tok
+                # `speed` is an internal pricing input, not part of the public
+                # token-count object. Keep it alongside the assembled item for
+                # cache financials and strip it from reader page copies.
+                it["tokens"] = {k: v for k, v in tok.items() if k != "speed"}
+                it["_speed"] = tok.get("speed")
             del it["_msg_id"]
             del it["_req_id"]
             it.pop("_has_prose", None)
@@ -2276,6 +2321,7 @@ def get_conversation(conn, session_id, *, after=None, before=None, tail=False,
     patched = []
     for it in page:
         nit = dict(it)
+        nit.pop("_speed", None)
         nit["anchor"] = {**it["anchor"], "session_id": session_id}
         if nit.get("text"):
             nit["text"] = _strip_ansi(nit["text"])
@@ -2422,7 +2468,9 @@ def get_conversation_outline(conn, session_id):
                     tokens[k] += tok.get(k, 0)
                 cr_tokens = tok.get("cache_read", 0) or 0
                 if cr_tokens > 0:
-                    cache_saved += _cache_read_saved_usd(it.get("model"), cr_tokens)
+                    cache_saved += _cache_read_saved_usd(
+                        it.get("model"), cr_tokens, speed=it.get("_speed")
+                    )
             # Copy the cache-failure marker onto the OutlineTurn exactly where
             # tokens is copied (assistant-only, rides the same source row) and
             # accumulate the session-level aggregate (spec §2).

package/bin/_lib_dashboard_sources.py

@@ -17,6 +17,7 @@ PhysicalSource = Literal["claude", "codex"]
 DashboardSelection = Literal["claude", "codex", "all"]
 Availability = Literal["ok", "empty", "partial", "unavailable"]
 Freshness = Literal["fresh", "stale"]
+FreshnessDomain = Literal["hero", "quota", "sessions"]
 CapabilityStatus = Literal[
     "supported", "derived", "unavailable", "deferred", "not_applicable",
 ]
@@ -24,6 +25,7 @@ CapabilityStatus = Literal[
 SOURCE_SCHEMA_VERSION = 1
 DEFAULT_SOURCE = "claude"
 SOURCE_ORDER = ("claude", "codex", "all")
+SOURCE_FRESHNESS_DOMAINS = ("hero", "quota", "sessions")
 
 _PHYSICAL_SOURCES = frozenset(("claude", "codex"))
 _SELECTIONS = frozenset(SOURCE_ORDER)
@@ -109,10 +111,19 @@ class SourceDashboardState:
     last_success_at: dt.datetime | None
     capabilities: Mapping[str, CapabilityRecord]
     data: Mapping[str, object] | None
+    # Domain freshness is orthogonal to provider-generation coherence. Legacy
+    # constructors may omit it; they deterministically inherit the provider
+    # value for every known domain.
+    domain_freshness: Mapping[str, Freshness] | None = None
     # Immutable, server-only facts used to advance an idle presentation clock.
     # They are deliberately separate from ``data`` so no internal accounting
     # evidence becomes part of the public source-envelope contract.
     clock_data: Mapping[str, object] | None = None
+    # Request-gated transcript content. This mapping is frozen with the source
+    # generation but is deliberately outside ``data``: source serialization
+    # publishes only ``data``, then the HTTP/SSE envelope layer injects a label
+    # into its request-local copies when that request's transcript gate is open.
+    private_session_labels: Mapping[str, str] | None = None
 
     def __post_init__(self) -> None:
         validate_dashboard_selection(self.source)
@@ -120,6 +131,16 @@ class SourceDashboardState:
             raise ValueError("unsupported availability")
         if self.freshness not in _FRESHNESS:
             raise ValueError("unsupported freshness")
+        domain_freshness = (
+            {domain: self.freshness for domain in SOURCE_FRESHNESS_DOMAINS}
+            if self.domain_freshness is None else dict(self.domain_freshness)
+        )
+        if set(domain_freshness) != set(SOURCE_FRESHNESS_DOMAINS):
+            raise ValueError(
+                "domain freshness must contain exactly hero, quota, and sessions"
+            )
+        if any(value not in _FRESHNESS for value in domain_freshness.values()):
+            raise ValueError("unsupported domain freshness")
         if not isinstance(self.data_version, str):
             raise ValueError("data_version must be a string")
         if self.availability != "unavailable":
@@ -141,10 +162,20 @@ class SourceDashboardState:
             raise ValueError("capabilities must contain CapabilityRecord values")
         object.__setattr__(self, "warnings", warnings)
         object.__setattr__(self, "capabilities", _freeze(capabilities))
+        object.__setattr__(self, "domain_freshness", _freeze(domain_freshness))
         if self.data is not None:
             object.__setattr__(self, "data", _freeze(self.data))
         if self.clock_data is not None:
             object.__setattr__(self, "clock_data", _freeze(self.clock_data))
+        if self.private_session_labels is not None:
+            private_session_labels = {
+                _nonempty_string(key, "private session label key"):
+                _nonempty_string(value, "private session label")
+                for key, value in self.private_session_labels.items()
+            }
+            object.__setattr__(
+                self, "private_session_labels", _freeze(private_session_labels),
+            )
 
 
 @dataclass(frozen=True)
@@ -246,7 +277,11 @@ def degrade_source_state(
         last_success_at=prior.last_success_at,
         capabilities=prior.capabilities,
         data=prior.data,
+        domain_freshness={
+            domain: "stale" for domain in SOURCE_FRESHNESS_DOMAINS
+        },
         clock_data=prior.clock_data,
+        private_session_labels=prior.private_session_labels,
     )
 
 
@@ -267,9 +302,28 @@ def unavailable_source_state(
         last_success_at=None,
         capabilities={},
         data=None,
+        domain_freshness={
+            domain: "stale" for domain in SOURCE_FRESHNESS_DOMAINS
+        },
     )
 
 
+def source_domain_freshness(
+    state: SourceDashboardState,
+    domain: FreshnessDomain,
+) -> Freshness:
+    """Return one domain value with the frozen legacy-provider fallback."""
+    if domain not in SOURCE_FRESHNESS_DOMAINS:
+        raise ValueError("unsupported freshness domain")
+    mapping = getattr(state, "domain_freshness", None)
+    if isinstance(mapping, Mapping):
+        value = mapping.get(domain)
+        if value in _FRESHNESS:
+            return value
+    provider = getattr(state, "freshness", "stale")
+    return provider if provider in _FRESHNESS else "stale"
+
+
 def _coherent_provider(state: SourceDashboardState) -> bool:
     return (
         state.availability in ("ok", "empty", "partial")
@@ -303,6 +357,8 @@ def _hero_cycle_is_stale(state: SourceDashboardState) -> bool:
     ``hero.cycle_freshness`` is additive and OMITTED while the cycle is fresh, so
     this is false for every provider and every generation that predates #350.
     """
+    if source_domain_freshness(state, "hero") == "stale":
+        return True
     if not isinstance(state.data, Mapping):
         return False
     hero = state.data.get("hero")
@@ -429,7 +485,15 @@ def compose_all_state(
     version_material = json.dumps(
         [
             claude.data_version, claude.availability, claude.freshness,
+            [
+                source_domain_freshness(claude, domain)
+                for domain in SOURCE_FRESHNESS_DOMAINS
+            ],
             codex.data_version, codex.availability, codex.freshness,
+            [
+                source_domain_freshness(codex, domain)
+                for domain in SOURCE_FRESHNESS_DOMAINS
+            ],
             combined is not None,
         ],
         separators=(",", ":"),
@@ -462,6 +526,17 @@ def compose_all_state(
                 "codex": codex.data,
             },
         },
+        domain_freshness={
+            domain: (
+                "fresh"
+                if all(
+                    source_domain_freshness(state, domain) == "fresh"
+                    for state in (claude, codex)
+                )
+                else "stale"
+            )
+            for domain in SOURCE_FRESHNESS_DOMAINS
+        },
     )
 
 

package/bin/_lib_diff_kernel.py

@@ -110,6 +110,8 @@ def _load_lib(name: str):
 
 _lib_pricing = _load_lib("_lib_pricing")
 _calculate_entry_cost = _lib_pricing._calculate_entry_cost
+# #195: the single construction point for every cost-feeding usage dict.
+claude_usage_dict = _lib_pricing.claude_usage_dict
 
 _lib_display_tz = _load_lib("_lib_display_tz")
 _resolve_tz = _lib_display_tz._resolve_tz
@@ -512,12 +514,14 @@ def _diff_aggregate_overall(
             continue
         cost += _calculate_entry_cost(
             e.model,
-            {
-                "input_tokens": e.input_tokens,
-                "output_tokens": e.output_tokens,
-                "cache_creation_input_tokens": e.cache_creation_tokens,
-                "cache_read_input_tokens": e.cache_read_tokens,
-            },
+            claude_usage_dict(   # #195 chokepoint
+                input_tokens=e.input_tokens,
+                output_tokens=e.output_tokens,
+                cache_creation_tokens=e.cache_creation_tokens,
+                cache_read_tokens=e.cache_read_tokens,
+                cache_1h_tokens=getattr(e, "cache_1h_tokens", None),
+                speed=getattr(e, "speed", None),
+            ),
             mode="auto",
             cost_usd=e.cost_usd,
         )
@@ -552,9 +556,12 @@ def _diff_aggregate_models(
         })
         b["cost"] += _calculate_entry_cost(
             e.model,
-            {"input_tokens": e.input_tokens, "output_tokens": e.output_tokens,
-             "cache_creation_input_tokens": e.cache_creation_tokens,
-             "cache_read_input_tokens": e.cache_read_tokens},
+            claude_usage_dict(   # #195 chokepoint
+                input_tokens=e.input_tokens, output_tokens=e.output_tokens,
+                cache_creation_tokens=e.cache_creation_tokens,
+                cache_read_tokens=e.cache_read_tokens,
+                cache_1h_tokens=getattr(e, "cache_1h_tokens", None),
+                speed=getattr(e, "speed", None)),
             mode="auto", cost_usd=e.cost_usd,
         )
         b["ti"] += e.input_tokens
@@ -593,9 +600,12 @@ def _diff_aggregate_projects(
         })
         b["cost"] += _calculate_entry_cost(
             e.model,
-            {"input_tokens": e.input_tokens, "output_tokens": e.output_tokens,
-             "cache_creation_input_tokens": e.cache_creation_tokens,
-             "cache_read_input_tokens": e.cache_read_tokens},
+            claude_usage_dict(   # #195 chokepoint
+                input_tokens=e.input_tokens, output_tokens=e.output_tokens,
+                cache_creation_tokens=e.cache_creation_tokens,
+                cache_read_tokens=e.cache_read_tokens,
+                cache_1h_tokens=getattr(e, "cache_1h_tokens", None),
+                speed=getattr(e, "speed", None)),
             mode="auto", cost_usd=e.cost_usd,
         )
         b["ti"] += e.input_tokens
@@ -639,9 +649,12 @@ def _diff_aggregate_cache(
             continue
         cost += _calculate_entry_cost(
             e.model,
-            {"input_tokens": e.input_tokens, "output_tokens": e.output_tokens,
-             "cache_creation_input_tokens": e.cache_creation_tokens,
-             "cache_read_input_tokens": e.cache_read_tokens},
+            claude_usage_dict(   # #195 chokepoint
+                input_tokens=e.input_tokens, output_tokens=e.output_tokens,
+                cache_creation_tokens=e.cache_creation_tokens,
+                cache_read_tokens=e.cache_read_tokens,
+                cache_1h_tokens=getattr(e, "cache_1h_tokens", None),
+                speed=getattr(e, "speed", None)),
             mode="auto", cost_usd=e.cost_usd,
         )
         tcr += e.cache_read_tokens