imbue-mngr-usage 0.1.0__tar.gz

imbue_mngr_usage-0.1.0/.gitignore

@@ -0,0 +1,346 @@
+# Byte-compiled / optimized / DLL files
+**/__pycache__/
+**/*.py[codz]
+**/*$py.class
+
+# macOS Finder metadata
+**/.DS_Store
+
+# C extensions
+**/*.so
+
+# Distribution / packaging
+**/.Python
+**/build/
+**/develop-eggs/
+**/dist/
+**/downloads/
+**/eggs/
+**/.eggs/
+**/lib/
+**/lib64/
+**/parts/
+**/sdist/
+**/var/
+**/wheels/
+**/share/python-wheels/
+**/*.egg-info/
+**/.installed.cfg
+**/*.egg
+**/MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+**/*.manifest
+**/*.spec
+
+# Installer logs
+**/pip-log.txt
+**/pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+**/htmlcov/
+**/.tox/
+**/.nox/
+**/.coverage
+**/.coverage.*
+**/.cache
+**/nosetests.xml
+**/coverage.xml
+**/*.cover
+**/*.py.cover
+**/.hypothesis/
+**/.pytest_cache/
+**/cover/
+
+# Translations
+**/*.mo
+**/*.pot
+
+# Django stuff:
+**/*.log
+**/local_settings.py
+**/db.sqlite3
+**/db.sqlite3-journal
+
+# Flask stuff:
+**/instance/
+**/.webassets-cache
+
+# Scrapy stuff:
+**/.scrapy
+
+# Sphinx documentation
+**/docs/_build/
+
+# PyBuilder
+**/.pybuilder/
+**/target/
+
+# Jupyter Notebook
+**/.ipynb_checkpoints
+
+# IPython
+**/profile_default/
+**/ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+**/.pdm-python
+**/.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+**/.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+**/__pypackages__/
+
+# Celery stuff
+**/celerybeat-schedule
+**/celerybeat.pid
+
+# SageMath parsed files
+**/*.sage.py
+
+# Environments
+**/.env
+**/.envrc
+**/.venv
+**/.venv-*
+**/env/
+**/venv/
+**/ENV/
+**/env.bak/
+**/venv.bak/
+
+# Spyder project settings
+**/.spyderproject
+**/.spyproject
+
+# Rope project settings
+**/.ropeproject
+
+# mkdocs documentation
+**/site
+
+# mypy
+**/.mypy_cache/
+**/.dmypy.json
+**/dmypy.json
+
+# Pyre type checker
+**/.pyre/
+
+# pytype static type analyzer
+**/.pytype/
+
+# Cython debug symbols
+**/cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+**/.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+**/.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+**/.ruff_cache/
+
+# PyPI configuration file
+**/.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+**/.cursorignore
+**/.cursorindexingignore
+
+# Marimo
+**/marimo/_static/
+**/marimo/_lsp/
+**/__marimo__/
+
+# task folders for local custom claude workflow
+*/*/_tasks/
+**/.sesskey
+
+# Node.js
+**/node_modules/
+
+# Frontend build artifacts
+**/frontend-dist/
+
+# Claude Code local settings (session-specific permissions)
+**/.claude/settings.local.json
+
+# Local Claude settings backup files
+**/.claude/*.bak
+
+# Claude worktress
+**/.claude/worktrees
+
+# Agent definitions deployed by mngr_subagent_proxy at session start
+**/.claude/agents/
+
+# Local mngr settings (not committed)
+**/.mngr/settings.local.toml
+
+# Local working / scratch markdown (not committed)
+**/*.local.md
+
+# Local working / scratch shell scripts (not committed)
+# (covers user notification scripts like scripts/notify_user.local.sh, too)
+**/*.local.sh
+
+# Test output files (slow tests, coverage summaries)
+**/.test_output/
+
+# TMR output directories (reports + test outputs)
+**/tmr_*/
+
+# Active session marker file (used to detect interrupted sessions)
+**/.claude/active
+
+# we stick the image build artifacts here
+**/.mngr/dev/build/
+**/.mngr/dev/secrets/
+
+# Offload caches and local files
+**/.offload/**
+**/test-results
+
+# Minds deploy-time build artifacts.
+# Ignore contents so we can un-ignore the committed `template/` subtree: git
+# won't descend into a fully-ignored directory, so negations must live below
+# the contents pattern rather than below the directory pattern.
+**/.minds/*
+# The template directory is committed: it defines the expected keys for each
+# <service>.sh file, with empty values. `scripts/push_modal_secrets.py` uses
+# it to check that per-env .sh files declare every template key.
+!/.minds/template/
+!/.minds/template/**
+# Vault ACL policies for the minds tiers. The HCL is non-sensitive and is
+# the source of truth for the policies pushed to Vault via
+# `vault policy write <name> .minds/policies/<name>.hcl`.
+!/.minds/policies/
+!/.minds/policies/**
+
+# Autofix session artifacts
+**/.autofix/
+**/.reviewer/logs/
+**/.reviewer/outputs/
+**/.reviewer/settings.local.json
+**/.reviewer/.stop_hook_consecutive_blocks
+**/.reviewer/conversation-issues.jsonl
+**/.reviews/
+
+# Stuck agent tracking (stop hook escape valve)
+**/.claude/blocked_stop_commits
+
+# Scheduled tasks lock file
+**/.claude/scheduled_tasks.lock
+
+# Demo recordings (asciinema .cast, .txt, and scripts)
+**/.demos/
+
+# for git worktrees from other repos
+**/.external_worktrees/
+
+# ignore coverage files generated within subprojects
+**/cov.xml
+
+# ignore demos
+**/recordings
+
+# Generated by the _generate-dockerignore justfile recipe before each
+# test-offload* run. The recipe strips this self-reference so offload's
+# copy_untracked_files ships the generated file into the build context.
+/.dockerignore
+
+# Transient offload image-cache marker written by test-offload runs; not
+# checked in (unlike the committed .offload-*-cache-key files which pin CI
+# image versions).
+/.offload-image-cache
+
+# Generated by _generate-release-dockerfile from Dockerfile + .release.extras.
+/libs/mngr/imbue/mngr/resources/Dockerfile.release
+**/.reviewer/autofix/issues/
+.reviewer/logs/
+
+# Tailwind Play CDN JS for the minds desktop client. Fetched once via
+# `just minds-tailwind` (plain curl, no build) and shipped with the
+# distributable. Not checked in because it's a ~300KB blob we can always
+# re-fetch.
+/apps/minds/imbue/minds/desktop_client/static/tailwind.js
+**/.env.swp
+# Vim swap files for any file (`.foo.swp`, `.foo.swo`, etc.) -- generated
+# while a file is open in vim. Never checked in.
+**/.*.sw[a-p]
+
+# `minds env deploy` writes a recover-target file at the monorepo root
+# on failed deploys; `minds env recover` deletes it after rolling back.
+# Never checked in. Per-env naming
+# (``.minds-deploy-recover-target-<env-name>.json``) means each in-flight
+# deploy has its own file, so concurrent deploys against different envs
+# don't trip over each other.
+**/.minds-deploy-*.json
+# Per-env deploy lock files (kernel-level ``flock`` targets). Created
+# by ``hold_deploy_lock`` in ``apps/minds/imbue/minds/envs/recover.py``
+# and held for the entire duration of ``minds env deploy`` /
+# ``minds env recover`` so two concurrent invocations against the same
+# env serialize. The file itself is empty and cheap to leave around.
+**/.minds-deploy-lock-*.lock
+**/.antigravitycli/
+
+# Playwright MCP scratch artifacts (mock screenshots, page snapshots)
+**/.playwright-mcp/

imbue_mngr_usage-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog - mngr_usage
+
+A concise, human-friendly summary of changes for the `mngr_usage` library. Entries are categorized using the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories: Added, Changed, Deprecated, Removed, Fixed, Security.
+
+For the full, unedited changelog entries, see [UNABRIDGED_CHANGELOG.md](UNABRIDGED_CHANGELOG.md).
+
+## [Unreleased]
+
+## [v0.1.0] - 2026-06-05
+
+### Added
+
+- Added: `mngr usage` per-session cost aggregation with separate `subscription_cost` / `api_cost` aggregates, `--since`, `--detail`, and CEL/format-template surfaces; cost tracking now works for direct `ANTHROPIC_API_KEY` users.
+- Added: New `docs/cron_recipes.md` "cron automation recipes" doc (linked from the README) with worked examples of driving `mngr` from cron using check mode (`mngr usage --format json`) rather than the blocking `mngr usage wait`, plus a shared `spare-capacity.sh` helper (exit 0 when the 5h window still has budget and the week is under pace). Worked examples cover: using up an about-to-expire 5h window via a dedicated agent's full lifecycle, warming a fresh 5h window early so it resets partway through your work, and dispatching a queue of task files capped by a shared `queue=live` label.
+- Added: The usage plugin contributes its cron-recipes documentation as a `mngr help usage_cron_recipes` topic via mngr's new `register_help_topics` hook. The topic body is the plugin's `cron_recipes.md`, shipped inside the wheel via `force-include`, and its `DocFile` carries a GitHub `source_url` so relative links (e.g. `[Waiting on a predicate](../README.md#waiting-on-a-predicate)`) are rewritten to clickable absolute GitHub URLs in an interactive terminal.
+
+### Changed
+
+- Changed: Added to the release tooling's publish graph (`scripts/utils.py`); will be offered for first publication to PyPI on the next release. Stale `imbue-mngr==0.2.6` pin in `pyproject.toml` is realigned to the current `0.2.10`. No runtime change.
+
+## [v0.2.8] - 2026-05-13
+
+### Added
+
+- Added: New `mngr usage` command reporting Claude Code's rolling 5h / 7d / overage quota usage with `human`/`json`/`jsonl` formats and the standard agent-filter flags.
+- Added: New `mngr usage wait --until <CEL>` command that blocks until a usage snapshot matches a predicate, with exit codes mirroring `mngr wait`.

imbue_mngr_usage-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: imbue-mngr-usage
+Version: 0.1.0
+Summary: mngr usage subcommand: agent-agnostic rolling-window quota / usage CLI (provider plugins implement the data side via the current_usage_snapshot hook)
+Requires-Python: >=3.12
+Requires-Dist: click-option-group>=0.5.6
+Requires-Dist: click>=8.0
+Requires-Dist: imbue-mngr==0.2.11
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# imbue-mngr-usage
+
+`mngr usage` -- agent-agnostic CLI for rolling-window usage / quota data.
+
+## What it does
+
+Provides a single `mngr usage` command that surfaces rolling-window usage data
+in human / json / jsonl / format-template output. The command itself knows
+nothing about any specific agent type or provider; it walks events files on
+disk and renders whatever it finds.
+
+## Architecture
+
+This package contains:
+
+- The `mngr usage` CLI command and its rendering helpers.
+- The `UsageSnapshot`, `WindowSnapshot`, and `CostSnapshot` data types.
+
+Discovery is by path convention. The CLI walks
+`<host_dir>/agents/*/events/<source>/usage/events.jsonl` (the same shape
+`mngr transcript` uses for `events/<source>/common_transcript/...`), scans
+every event line, and aggregates per `<source>`: rate-limit windows
+collapse freshest-wins (the account-level counter), while cost is grouped
+per `session_id` and filtered to a recency window (`--since`, default 24h).
+The `<source>` segment is free-form -- whatever the writer plugin chose.
+
+When multiple writers contribute, each renders as its own `[source]` section in
+human output and as an entry in the JSON `sources` array.
+
+## Output formats
+
+- `mngr usage` (human summary: per-mode cost line(s) + window lines)
+- `mngr usage --detail` (human + per-session breakdown lines)
+- `mngr usage --format json` (summary JSON: per-mode aggregates `subscription_cost` and `api_cost`, `session_count` plus per-mode counts, windows)
+- `mngr usage --format json --detail` (JSON with `sessions[]` per source; each session carries a `cost_mode` tag)
+- `mngr usage --format jsonl`
+- `mngr usage --format '5h:{five_hour.used_percentage}%/{seven_day.used_percentage}%'`
+
+The `--detail` flag is independent of `--verbose` (which controls log
+level). It toggles only the per-session breakdown surfaces.
+
+## Waiting on a predicate
+
+`mngr usage wait --until <CEL>` blocks until at least one source's CEL
+context satisfies every `--until` expression, then exits 0. Composable with
+shell:
+
+```
+mngr usage wait --until 'five_hour.elapsed_percentage > 75 && five_hour.used_percentage < 50' \
+  && mngr message my-agent "ok, kick off the next batch"
+```
+
+The CEL context per source mirrors one entry of `mngr usage --format json`'s
+`sources` array. Each window exposes the writer-emitted fields
+(`used_percentage`, `resets_at`, `window_seconds`, `label`, ...) plus the
+reader-derived `seconds_until_reset`, `elapsed_seconds`, and
+`elapsed_percentage` (the last two require `window_seconds` from the
+writer; absent on variable-duration windows like Claude's overage).
+Source-level fields are exposed too. Cost is split by auth mode and
+**never lumped**: `subscription_cost.*` aggregates sessions whose Claude
+Code process was on a Claude.ai Pro/Max subscription (cost is **imputed**
+by Claude Code -- the user actually pays a flat subscription), and
+`api_cost.*` aggregates sessions whose process was on a direct
+`ANTHROPIC_API_KEY` (cost is **real** billable spend). Pick the mode you
+care about, e.g. `api_cost.total_cost_usd > 20.0` means "I've spent more
+than $20 of real API money across recent sessions". `session_count` is
+the total across both modes; `subscription_session_count` and
+`api_session_count` break that down per mode. `since_seconds` and
+`sessions[]` (every session in the window, newest-first, each carrying
+a `cost_mode` of `"SUBSCRIPTION"` or `"API_KEY"`) are available as well.
+Use `--since` to tighten or widen the aggregation window from its
+default (24h). For a per-session predicate, index `sessions[]` directly
+(e.g. `sessions[0].cost.total_cost_usd > 5` for the most recent
+session's own contribution).
+
+Exit codes mirror `mngr wait`: 0 matched, 1 error, 2 timeout. Default poll
+interval is 30s; use `--interval` for tighter cadence. To restrict matching
+to a specific writer, use the top-level `source` field in CEL (e.g.
+`--until 'source == "claude" && five_hour.used_percentage < 50'`).
+
+## Polling from cron (check mode)
+
+For recurring automation, let `cron` own the cadence: poll the plain
+`mngr usage --format json` snapshot on a schedule and branch in the shell. See
+[cron automation recipes](docs/cron_recipes.md) for worked examples: using up an
+about-to-expire 5h window (with a weekly pace check), warming a fresh window the
+moment the last one elapses, and working through a queue of task files a couple
+at a time.
+
+## Implementing a writer plugin
+
+A writer plugin is responsible for producing `cost_snapshot` events at the
+conventional path. The minimal contract is just the JSONL line shape:
+
+```jsonl
+{"source":"<your-source>/usage","type":"cost_snapshot","event_id":"evt-<hex>","timestamp":"<ISO 8601>","session_id":"<uuid>","cost":{"total_cost_usd":<float>},"rate_limits":{"<window-key>":{"used_percentage":<float>,"resets_at":<unix-ts>}}}
+```
+
+Every event must carry a `session_id` (non-empty string) plus at least one
+of `rate_limits` or `cost`. Events missing `session_id` are dropped with a
+WARNING log naming the source and event_id -- so if you're writing a usage
+plugin and don't see your data in `mngr usage`, check the log first. Any
+plausible statusline source has a session identifier handy, so this is
+rarely a constraint; if a future tool doesn't, synthesize a stable
+per-session id on the writer side. The `type` field is informational --
+the reader doesn't validate it -- but `"cost_snapshot"` is the current
+convention.
+
+Append one line per refresh to:
+
+```
+<agent_state_dir>/events/<your-source>/usage/events.jsonl
+```
+
+`mngr usage` will pick it up automatically -- no plugin registration with this
+package required.
+
+The writer chooses both the window keys and (optionally) per-window
+`label`s. Keys are used by format templates (`{<key>.used_percentage}`) and
+should be identifier-safe if you want format-template support; the per-window
+`label` controls human display (e.g. `"5h"` vs the literal key `"five_hour"`).
+Render order is the writer's insertion order in the JSONL.
+
+Writers may also include `"window_seconds": <int>` per window to declare a
+fixed window duration. When present, `mngr usage` derives `elapsed_seconds`
+and `elapsed_percentage`, which `mngr usage wait` CEL predicates can use to
+express "75% of the window has elapsed" without callers hardcoding window
+durations. Omit `window_seconds` for windows without a fixed length (e.g.
+Claude's overage indicator).

imbue_mngr_usage-0.1.0/README.md

@@ -0,0 +1,129 @@
+# imbue-mngr-usage
+
+`mngr usage` -- agent-agnostic CLI for rolling-window usage / quota data.
+
+## What it does
+
+Provides a single `mngr usage` command that surfaces rolling-window usage data
+in human / json / jsonl / format-template output. The command itself knows
+nothing about any specific agent type or provider; it walks events files on
+disk and renders whatever it finds.
+
+## Architecture
+
+This package contains:
+
+- The `mngr usage` CLI command and its rendering helpers.
+- The `UsageSnapshot`, `WindowSnapshot`, and `CostSnapshot` data types.
+
+Discovery is by path convention. The CLI walks
+`<host_dir>/agents/*/events/<source>/usage/events.jsonl` (the same shape
+`mngr transcript` uses for `events/<source>/common_transcript/...`), scans
+every event line, and aggregates per `<source>`: rate-limit windows
+collapse freshest-wins (the account-level counter), while cost is grouped
+per `session_id` and filtered to a recency window (`--since`, default 24h).
+The `<source>` segment is free-form -- whatever the writer plugin chose.
+
+When multiple writers contribute, each renders as its own `[source]` section in
+human output and as an entry in the JSON `sources` array.
+
+## Output formats
+
+- `mngr usage` (human summary: per-mode cost line(s) + window lines)
+- `mngr usage --detail` (human + per-session breakdown lines)
+- `mngr usage --format json` (summary JSON: per-mode aggregates `subscription_cost` and `api_cost`, `session_count` plus per-mode counts, windows)
+- `mngr usage --format json --detail` (JSON with `sessions[]` per source; each session carries a `cost_mode` tag)
+- `mngr usage --format jsonl`
+- `mngr usage --format '5h:{five_hour.used_percentage}%/{seven_day.used_percentage}%'`
+
+The `--detail` flag is independent of `--verbose` (which controls log
+level). It toggles only the per-session breakdown surfaces.
+
+## Waiting on a predicate
+
+`mngr usage wait --until <CEL>` blocks until at least one source's CEL
+context satisfies every `--until` expression, then exits 0. Composable with
+shell:
+
+```
+mngr usage wait --until 'five_hour.elapsed_percentage > 75 && five_hour.used_percentage < 50' \
+  && mngr message my-agent "ok, kick off the next batch"
+```
+
+The CEL context per source mirrors one entry of `mngr usage --format json`'s
+`sources` array. Each window exposes the writer-emitted fields
+(`used_percentage`, `resets_at`, `window_seconds`, `label`, ...) plus the
+reader-derived `seconds_until_reset`, `elapsed_seconds`, and
+`elapsed_percentage` (the last two require `window_seconds` from the
+writer; absent on variable-duration windows like Claude's overage).
+Source-level fields are exposed too. Cost is split by auth mode and
+**never lumped**: `subscription_cost.*` aggregates sessions whose Claude
+Code process was on a Claude.ai Pro/Max subscription (cost is **imputed**
+by Claude Code -- the user actually pays a flat subscription), and
+`api_cost.*` aggregates sessions whose process was on a direct
+`ANTHROPIC_API_KEY` (cost is **real** billable spend). Pick the mode you
+care about, e.g. `api_cost.total_cost_usd > 20.0` means "I've spent more
+than $20 of real API money across recent sessions". `session_count` is
+the total across both modes; `subscription_session_count` and
+`api_session_count` break that down per mode. `since_seconds` and
+`sessions[]` (every session in the window, newest-first, each carrying
+a `cost_mode` of `"SUBSCRIPTION"` or `"API_KEY"`) are available as well.
+Use `--since` to tighten or widen the aggregation window from its
+default (24h). For a per-session predicate, index `sessions[]` directly
+(e.g. `sessions[0].cost.total_cost_usd > 5` for the most recent
+session's own contribution).
+
+Exit codes mirror `mngr wait`: 0 matched, 1 error, 2 timeout. Default poll
+interval is 30s; use `--interval` for tighter cadence. To restrict matching
+to a specific writer, use the top-level `source` field in CEL (e.g.
+`--until 'source == "claude" && five_hour.used_percentage < 50'`).
+
+## Polling from cron (check mode)
+
+For recurring automation, let `cron` own the cadence: poll the plain
+`mngr usage --format json` snapshot on a schedule and branch in the shell. See
+[cron automation recipes](docs/cron_recipes.md) for worked examples: using up an
+about-to-expire 5h window (with a weekly pace check), warming a fresh window the
+moment the last one elapses, and working through a queue of task files a couple
+at a time.
+
+## Implementing a writer plugin
+
+A writer plugin is responsible for producing `cost_snapshot` events at the
+conventional path. The minimal contract is just the JSONL line shape:
+
+```jsonl
+{"source":"<your-source>/usage","type":"cost_snapshot","event_id":"evt-<hex>","timestamp":"<ISO 8601>","session_id":"<uuid>","cost":{"total_cost_usd":<float>},"rate_limits":{"<window-key>":{"used_percentage":<float>,"resets_at":<unix-ts>}}}
+```
+
+Every event must carry a `session_id` (non-empty string) plus at least one
+of `rate_limits` or `cost`. Events missing `session_id` are dropped with a
+WARNING log naming the source and event_id -- so if you're writing a usage
+plugin and don't see your data in `mngr usage`, check the log first. Any
+plausible statusline source has a session identifier handy, so this is
+rarely a constraint; if a future tool doesn't, synthesize a stable
+per-session id on the writer side. The `type` field is informational --
+the reader doesn't validate it -- but `"cost_snapshot"` is the current
+convention.
+
+Append one line per refresh to:
+
+```
+<agent_state_dir>/events/<your-source>/usage/events.jsonl
+```
+
+`mngr usage` will pick it up automatically -- no plugin registration with this
+package required.
+
+The writer chooses both the window keys and (optionally) per-window
+`label`s. Keys are used by format templates (`{<key>.used_percentage}`) and
+should be identifier-safe if you want format-template support; the per-window
+`label` controls human display (e.g. `"5h"` vs the literal key `"five_hour"`).
+Render order is the writer's insertion order in the JSONL.
+
+Writers may also include `"window_seconds": <int>` per window to declare a
+fixed window duration. When present, `mngr usage` derives `elapsed_seconds`
+and `elapsed_percentage`, which `mngr usage wait` CEL predicates can use to
+express "75% of the window has elapsed" without callers hardcoding window
+durations. Omit `window_seconds` for windows without a fixed length (e.g.
+Claude's overage indicator).