cctally 1.27.0 → 1.28.0

package/bin/_cctally_weekrefs.py

@@ -233,6 +233,15 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
     effective reset moment is floored to the hour via `_floor_to_hour`
     so minute/second-level Anthropic jitter ("in X hr Y min" relative-text
     drift) doesn't masquerade as a reset.
+
+    ONE deliberate divergence from the live rule: backfill passes
+    ``allow_reset_to_zero=False`` to ``_is_reset_drop``, so it fires only on
+    the unambiguous ``>=25pp`` drop. The lenient reset-to-zero signal is
+    live-only — the live path debounces a transient API zero (issue #128),
+    but this one-shot historical scan has no debounce and would otherwise
+    mis-read a stale-replica 0% blip (``6% → 0% → 1%`` on a still-future
+    week_end) as a credit, segmenting the week into a degenerate zero-width
+    window. See ``_is_reset_drop`` for the full rationale.
     """
     c = _cctally()
     try:
@@ -278,7 +287,7 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
             if (
                 captured_dt < prior_end_dt
                 and prior_pct is not None and cur_pct is not None
-                and _is_reset_drop(prior_pct, cur_pct)
+                and _is_reset_drop(prior_pct, cur_pct, allow_reset_to_zero=False)
             ):
                 # Floor to the hour so the display boundary lands on the
                 # natural hour mark (Anthropic's reset times are always
@@ -309,7 +318,7 @@ def _backfill_week_reset_events(conn: sqlite3.Connection) -> None:
             if (
                 captured_dt < prior_end_dt
                 and prior_pct is not None and cur_pct is not None
-                and _is_reset_drop(prior_pct, cur_pct)
+                and _is_reset_drop(prior_pct, cur_pct, allow_reset_to_zero=False)
             ):
                 # Pre-check on ``new_week_end_at`` (mirrors the live
                 # detection path's pre-check). Necessary because the
@@ -392,7 +401,9 @@ _RESET_ZERO_FLOOR_PCT = 1.0
 _RESET_ZERO_MIN_DROP_PCT = 3.0
 
 
-def _is_reset_drop(prior_pct: float, cur_pct: float) -> bool:
+def _is_reset_drop(
+    prior_pct: float, cur_pct: float, *, allow_reset_to_zero: bool = True
+) -> bool:
     """True when ``prior_pct → cur_pct`` is a genuine weekly reset/credit.
 
     Two independent percent-shape signals (OR):
@@ -400,17 +411,30 @@ def _is_reset_drop(prior_pct: float, cur_pct: float) -> bool:
     * **Partial credit** — drop ``>= _RESET_PCT_DROP_THRESHOLD`` (25pp).
     * **Reset-to-zero** — ``cur_pct`` collapses to ~0
       (``<= _RESET_ZERO_FLOOR_PCT``) with a drop clearing
-      ``_RESET_ZERO_MIN_DROP_PCT``.
+      ``_RESET_ZERO_MIN_DROP_PCT``. Gated on ``allow_reset_to_zero``.
+
+    ``allow_reset_to_zero`` scopes the lenient reset-to-zero signal to the
+    sites that can afford it. **Live** current-week detection passes the
+    default ``True``: the live in-place path debounces a transient API zero
+    (issue #128 — arm on the first ~0, confirm only if it stays low, clear
+    on recovery). The **historical backfill**
+    (``_backfill_week_reset_events``) passes ``False`` — it is a one-shot
+    scan with NO debounce, so a single stale-replica 0% reading on a
+    still-future ``week_end`` (e.g. a ``6% → 0% → 1%`` blip) would otherwise
+    be mis-read as a goodwill credit and segment the week into a degenerate
+    zero-width window. Backfill therefore fires only on the unambiguous
+    ``>=25pp`` drop and defers sub-25pp reset-to-zero to the live path.
 
     Callers retain the boundary predicates (same/advanced ``week_end_at``
     AND ``prior_end_dt > now``); this helper owns ONLY the percent-shape
-    discrimination so all four 7d detection sites (live advance, live
-    in-place, backfill advance, backfill in-place) stay byte-identical.
+    discrimination.
     """
     cur = float(cur_pct)
     drop = float(prior_pct) - cur
     if drop >= _RESET_PCT_DROP_THRESHOLD:
         return True
+    if not allow_reset_to_zero:
+        return False
     return cur <= _RESET_ZERO_FLOOR_PCT and drop >= _RESET_ZERO_MIN_DROP_PCT
 
 

package/bin/_lib_alert_axes.py

@@ -37,7 +37,7 @@ def severity_for(threshold: int) -> str:
 class AlertAxisDescriptor:
     """Axis-agnostic metadata shared by the record path + dashboard envelope."""
 
-    id: str            # 'weekly' | 'five_hour' | 'budget' | 'projected' | 'project_budget'
+    id: str            # 'weekly' | 'five_hour' | 'budget' | 'projected' | 'project_budget' | 'codex_budget'
     chip_label: str    # SHOUT form, byte-identical with alertAxis.ts AXIS_CHIP_LABEL
     title_label: str   # sentence-case form, byte-identical with AXIS_TITLE_LABEL
     milestone_table: str  # SQLite table the dashboard envelope SELECTs from
@@ -53,6 +53,13 @@ AXIS_REGISTRY: "tuple[AlertAxisDescriptor, ...]" = (
     AlertAxisDescriptor(
         "project_budget", "PROJECT", "Project budget", "project_budget_milestones"
     ),
+    # Per-vendor Codex budget alerts (calendar-period; calendar-period-codex-budgets
+    # feature). Distinct "CODEX" chip vs the global "BUDGET" / per-project
+    # "PROJECT" chips; its own forward-only `codex_budget_milestones` table keyed
+    # on the resolved period-window start instant (period_start_at, threshold).
+    AlertAxisDescriptor(
+        "codex_budget", "CODEX", "Codex budget", "codex_budget_milestones"
+    ),
 )
 
 AXIS_BY_ID: "dict[str, AlertAxisDescriptor]" = {d.id: d for d in AXIS_REGISTRY}

package/bin/_lib_alerts_payload.py

@@ -222,13 +222,23 @@ def _build_alert_payload_budget(
     budget_usd: float,
     spent_usd: float,
     consumption_pct: float,
+    period: str = "subscription-week",
 ) -> dict:
     """Build the alert payload for an equiv-$ budget threshold crossing.
 
     See ``_build_alert_payload_weekly`` for the ``alerted_at == crossed_at``
     rationale (set-then-dispatch invariant). ``axis: "budget"`` is the third
     alert axis (Task 4 surfaces it in the dashboard Recent-alerts panel).
-    """
+
+    ``period`` defaults to ``subscription-week`` (the existing behavior — a
+    calendar-period-codex-budgets generalization, spec §6). The ``week_start_at``
+    key column carries the resolved PERIOD-start instant for a calendar period
+    (the name stays a back-compat misnomer, like ``weekly_usd``); the
+    additive ``period`` + ``period_start_at`` context fields let the dashboard
+    (Task 4) label "Month" / "Calendar week" instead of the hardcoded "Week".
+    The legacy subscription-week case is byte-stable on the rendered text — the
+    new context keys are purely additive and consumed only by the period-aware
+    label fix."""
     return {
         "id": f"budget:{week_start_at}:{threshold}",
         "axis": "budget",
@@ -237,6 +247,8 @@ def _build_alert_payload_budget(
         "alerted_at": crossed_at_utc,  # set-then-dispatch
         "context": {
             "week_start_at": week_start_at,
+            "period": str(period),
+            "period_start_at": week_start_at,
             "budget_usd": float(budget_usd),
             "spent_usd": float(spent_usd),
             "consumption_pct": float(consumption_pct),
@@ -314,6 +326,78 @@ def _build_alert_payload_project_budget(
     }
 
 
+def _alert_text_codex_budget(
+    payload: dict, tz: "ZoneInfo | None"
+) -> tuple[str, str, str]:
+    """Build (title, subtitle, body) for a Codex budget threshold alert (axis
+    ``codex_budget``, the sixth alert axis; calendar-period-codex-budgets spec
+    §6).
+
+    Mirrors :func:`_alert_text_budget` but labels the vendor (Codex) and the
+    civil period (Month / Calendar week) read from the period context so the
+    notification reads apart from a Claude budget alert. The rendered numbers
+    come from the payload (snapshotted at crossing), never live config that may
+    have changed since. ``period_start_at`` is an instant but the text doesn't
+    render it as a clock time, so no ``format_display_dt`` call is needed; ``tz``
+    is accepted for signature parity with peer ``_alert_text_*`` builders and
+    intentionally unused (same as ``_alert_text_budget``)."""
+    threshold = int(payload["threshold"])
+    ctx = payload.get("context") or {}
+    period = ctx.get("period")
+    period_label = {
+        "calendar-month": "this month",
+        "calendar-week": "this week",
+    }.get(period, "this period")
+    title = "cctally - Codex budget"
+    subtitle = f"{threshold}% of Codex budget ({period_label})"
+    spent = float(ctx.get("spent_usd") or 0.0)
+    budget = float(ctx.get("budget_usd") or 0.0)
+    consumption = float(ctx.get("consumption_pct") or 0.0)
+    body = (
+        f"Codex - ${spent:,.2f} of ${budget:,.2f} "
+        f"({consumption:.0f}% of budget)"
+    )
+    return title, subtitle, body
+
+
+def _build_alert_payload_codex_budget(
+    *,
+    threshold: int,
+    crossed_at_utc: str,
+    period_start_at: str,
+    period: str,
+    budget_usd: float,
+    spent_usd: float,
+    consumption_pct: float,
+) -> dict:
+    """Build the alert payload for a Codex budget threshold crossing (axis
+    ``codex_budget``, the sixth alert axis; spec §6).
+
+    Mirrors :func:`_build_alert_payload_budget` but keyed on the resolved
+    CALENDAR-period window (``period_start_at`` in place of ``week_start_at``)
+    and carrying the period DISCRIMINATOR (``period`` = calendar-week /
+    calendar-month) in the context so the dashboard (Task 4) labels Month /
+    Calendar week instead of the hardcoded "Week". See
+    :func:`_build_alert_payload_weekly` for the ``alerted_at == crossed_at``
+    rationale (set-then-dispatch invariant). The dashboard envelope (Task 4)
+    surfaces this axis in the Recent-alerts panel from the row-sourced context.
+    """
+    return {
+        "id": f"codex_budget:{period_start_at}:{threshold}",
+        "axis": "codex_budget",
+        "threshold": int(threshold),
+        "crossed_at": crossed_at_utc,
+        "alerted_at": crossed_at_utc,  # set-then-dispatch
+        "context": {
+            "period": str(period),
+            "period_start_at": period_start_at,
+            "budget_usd": float(budget_usd),
+            "spent_usd": float(spent_usd),
+            "consumption_pct": float(consumption_pct),
+        },
+    }
+
+
 def _alert_text_projected(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str, str]:
     """Build (title, subtitle, body) for a projected-pace alert (#121).
 
@@ -334,6 +418,13 @@ def _alert_text_projected(payload: dict, tz: "ZoneInfo | None") -> tuple[str, st
         title = f"cctally - projected to reach {t}% this week"
         subtitle = "On current pace (projection)"
         body = f"Projected ~{proj:.0f}% of cap by reset (week-average pace)"
+    elif metric == "codex_budget_usd":
+        title = "cctally - Codex projected to exceed budget"
+        subtitle = f"On current pace (projection) - {t}% of Codex budget"
+        body = (
+            f"Projected ${proj:,.2f} of ${denom:,.2f} Codex budget "
+            f"(period-average pace)"
+        )
     else:  # budget_usd
         title = "cctally - projected to exceed budget"
         subtitle = f"On current pace (projection) - {t}% of budget"
@@ -355,8 +446,9 @@ def _build_alert_payload_projected(
     """Build the alert payload for a projected-pace threshold crossing (#121).
 
     ``axis: "projected"`` is the fourth alert axis; ``metric`` discriminates
-    ``weekly_pct`` (denominator 100.0, "% of cap") from ``budget_usd``
-    (denominator = target_usd, "$ of budget"). The frontend renders context
+    ``weekly_pct`` (denominator 100.0, "% of cap") from ``budget_usd`` and
+    ``codex_budget_usd`` (denominator = target_usd, "$ of budget"; the codex
+    variant renders Codex-flavored text). The frontend renders context
     FROM these row-sourced fields (``metric`` / ``projected_value`` /
     ``denominator``), not from live config that may have changed since crossing
     (Codex P0-4). No ``crossed_at``/``alerted_at`` keys here: the projected

package/bin/_lib_budget.py

@@ -33,6 +33,54 @@ def project_linear(
     return (current + rate_low * remaining, current + rate_high * remaining)
 
 
+def calendar_month_window(
+    now: dt.datetime, tz: dt.tzinfo
+) -> tuple[dt.datetime, dt.datetime]:
+    """Civil month window in ``tz``, returned as UTC-normalized instants.
+
+    Pure; no I/O. ``now`` is a tz-aware datetime and ``tz`` a tzinfo. Returns
+    ``(start_utc, end_utc)`` where ``start`` = the 1st of ``now``'s civil month
+    at 00:00 local and ``end`` = the 1st of the *next* month at 00:00 local
+    (civil rollover via ``(year, month + 1)`` with year carry — NEVER a fixed
+    ``timedelta(days=30)``, so 28/29/30/31-day months and Dec→Jan are exact),
+    both converted to UTC so the kernel's elapsed-seconds math stays single-tz.
+    """
+    local = now.astimezone(tz)
+    start_local = local.replace(
+        day=1, hour=0, minute=0, second=0, microsecond=0
+    )
+    if start_local.month == 12:
+        end_local = start_local.replace(year=start_local.year + 1, month=1)
+    else:
+        end_local = start_local.replace(month=start_local.month + 1)
+    return (
+        start_local.astimezone(dt.timezone.utc),
+        end_local.astimezone(dt.timezone.utc),
+    )
+
+
+def calendar_week_window(
+    now: dt.datetime, tz: dt.tzinfo, week_start_idx: int
+) -> tuple[dt.datetime, dt.datetime]:
+    """Civil week window in ``tz`` anchored on ``week_start_idx`` (Mon=0..Sun=6),
+    returned as UTC-normalized instants.
+
+    Pure; no I/O. Snaps ``now``'s local date back to the most recent
+    ``week_start_idx`` weekday at 00:00 local via ``(weekday − start_idx) % 7``,
+    then adds the 7-day delta to the *aware local* start so a DST week is a true
+    167h/169h span before normalizing both ends to UTC.
+    """
+    local = now.astimezone(tz)
+    midnight = local.replace(hour=0, minute=0, second=0, microsecond=0)
+    diff = (midnight.weekday() - week_start_idx) % 7
+    start_local = midnight - dt.timedelta(days=diff)
+    end_local = start_local + dt.timedelta(days=7)
+    return (
+        start_local.astimezone(dt.timezone.utc),
+        end_local.astimezone(dt.timezone.utc),
+    )
+
+
 @dataclass(frozen=True)
 class BudgetInputs:
     target_usd: float

package/bin/_lib_conversation.py

@@ -0,0 +1,162 @@
+"""Pure parser kernel for the conversation viewer (Plan 1).
+
+Turns Claude Code transcript JSONL lines into normalized conversation_messages
+rows. No DB, no clock, no I/O beyond the passed text-mode file handle — directly
+unit-testable. Mirrors _lib_jsonl.py's readline()+tell() byte-offset discipline
+so the message walk can share sync_cache's per-file cursor and rewind a partial
+mid-write tail line. Spec §1, §2.
+"""
+from __future__ import annotations
+import json
+from dataclasses import dataclass
+
+HUMAN = "human"
+ASSISTANT = "assistant"
+TOOL_RESULT = "tool_result"
+
+_TOOL_RESULT_CAP = 4000  # chars; full text always re-derivable from JSONL
+
+
+@dataclass
+class MessageRow:
+    byte_offset: int
+    session_id: "str | None"
+    uuid: "str | None"
+    parent_uuid: "str | None"
+    timestamp_utc: "str | None"
+    entry_type: str
+    text: str
+    blocks_json: str
+    model: "str | None"
+    msg_id: "str | None"
+    req_id: "str | None"
+    cwd: "str | None"
+    git_branch: "str | None"
+    is_sidechain: int
+
+
+def iter_message_rows(fh, path_str):
+    """Yield one MessageRow per user/assistant JSONL line from fh's current
+    position. summary / file-history-snapshot / malformed / uuid-less lines are
+    skipped (offset still advances). A partial tail line (no trailing newline)
+    rewinds the handle and stops, so the next sync re-reads it once complete.
+
+    ``path_str`` is accepted for caller symmetry — the sync ingest threads
+    ``source_path`` into each row at write time — but the kernel itself does
+    not use it (the returned MessageRow carries only ``byte_offset``)."""
+    while True:
+        offset = fh.tell()
+        line = fh.readline()
+        if not line:
+            return
+        if not line.endswith("\n"):
+            fh.seek(offset)
+            return
+        s = line.strip()
+        if not s:
+            continue
+        try:
+            obj = json.loads(s)
+        except json.JSONDecodeError:
+            continue
+        t = obj.get("type")
+        if t not in ("user", "assistant"):
+            continue
+        if not obj.get("uuid"):
+            continue
+        yield _normalize(obj, t, offset)
+
+
+def _normalize(obj, t, offset):
+    msg = obj.get("message")
+    if not isinstance(msg, dict):
+        msg = {}
+    blocks, text = _blocks_and_text(msg.get("content"))
+    if t == "assistant":
+        entry_type = ASSISTANT
+    elif any(b["kind"] == "tool_result" for b in blocks):
+        entry_type = TOOL_RESULT
+        # tool_result rows are stored but NOT indexed as prose (spec §2). A
+        # user line that mixes a text block with a tool_result block must not
+        # leak that text into the FTS index; the full content stays in
+        # blocks_json for rendering.
+        text = ""
+    else:
+        entry_type = HUMAN
+    is_asst = t == "assistant"
+    return MessageRow(
+        byte_offset=offset,
+        session_id=obj.get("sessionId"),
+        uuid=obj.get("uuid"),
+        parent_uuid=obj.get("parentUuid"),
+        timestamp_utc=obj.get("timestamp"),
+        entry_type=entry_type,
+        text=text,
+        blocks_json=json.dumps(blocks, separators=(",", ":")),
+        model=msg.get("model") if is_asst else None,
+        msg_id=msg.get("id") if is_asst else None,
+        req_id=obj.get("requestId") if is_asst else None,
+        cwd=obj.get("cwd"),
+        git_branch=obj.get("gitBranch"),
+        is_sidechain=1 if obj.get("isSidechain") else 0,
+    )
+
+
+def _blocks_and_text(content):
+    """Return (normalized blocks list, indexed-prose string). Prose = joined
+    `text` blocks only (thinking / tool_use / tool_result excluded)."""
+    if isinstance(content, str):
+        return ([{"kind": "text", "text": content}] if content else []), content
+    blocks, texts = [], []
+    if isinstance(content, list):
+        for b in content:
+            if not isinstance(b, dict):
+                continue
+            bt = b.get("type")
+            if bt == "text":
+                txt = b.get("text", "") or ""
+                blocks.append({"kind": "text", "text": txt})
+                texts.append(txt)
+            elif bt == "thinking":
+                blocks.append({"kind": "thinking", "text": b.get("thinking", "") or ""})
+            elif bt == "tool_use":
+                blocks.append({"kind": "tool_use", "name": b.get("name"),
+                               "input_summary": _summarize(b.get("input"))})
+            elif bt == "tool_result":
+                raw = _stringify(b.get("content"))
+                blocks.append({"kind": "tool_result", "text": raw[:_TOOL_RESULT_CAP],
+                               "truncated": len(raw) > _TOOL_RESULT_CAP,
+                               "is_error": bool(b.get("is_error"))})
+            elif bt in ("image", "document"):
+                blocks.append({"kind": bt, **_media(b.get("source"))})
+            elif bt == "tool_reference":
+                blocks.append({"kind": "tool_reference", "name": b.get("name")})
+    return blocks, "\n".join(t for t in texts if t)
+
+
+def _stringify(c):
+    if isinstance(c, str):
+        return c
+    if isinstance(c, list):
+        out = []
+        for b in c:
+            if isinstance(b, dict) and b.get("type") == "text":
+                out.append(b.get("text", "") or "")
+            elif isinstance(b, str):
+                out.append(b)
+        return "\n".join(out)
+    return "" if c is None else json.dumps(c, separators=(",", ":"))
+
+
+def _summarize(inp):
+    if not isinstance(inp, dict):
+        return ""
+    s = json.dumps(inp, separators=(",", ":"))
+    return s[:200]
+
+
+def _media(source):
+    if not isinstance(source, dict):
+        return {"media_type": None, "bytes": 0}
+    data = source.get("data") or ""
+    return {"media_type": source.get("media_type"), "bytes": len(data)}