@aaa-sentinel/ai-usage 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AAA Sentinel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# @aaa-sentinel/ai-usage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reports the usage of an **individual Cursor, Claude Code, GitHub Copilot or Codex seat** to
+AAA Sentinel, so a personal subscription shows which models it is spent on instead of only a
+plan percentage. The prompt, the code and the conversation stay on the laptop.
+
+## Requirements
+
+- Node.js 20 or newer.
+- An individual AI connection in AAA Sentinel (Cursor, Anthropic, Copilot or OpenAI) and the
+  enrollment token it issues. The token is shown once; rotating it invalidates the previous one.
+- For Copilot only: the [GitHub CLI](https://cli.github.com), already signed in (`gh auth login`)
+  to the account that holds the Copilot plan.
+
+## Install
+
+```bash
+npm install -g @aaa-sentinel/ai-usage
+```
+
+Save the token to a file only you can read, then pass it on **standard input**:
+
+```bash
+sentinel-usage login < token.txt
+```
+
+```powershell
+Get-Content -Raw -Encoding utf8 token.txt | sentinel-usage login
+```
+
+Delete the file when `login` finishes. The token is never accepted as an argument — it would stay
+in the shell history — and it is never read from the keyboard, so it is not echoed.
+
+`login` registers a startup task: at sign-in and every hour while a session is open (Task
+Scheduler on Windows, `launchd` on macOS, a `systemd` user timer on Linux). That task runs
+`sentinel-usage report`. You do not start anything when you sit down to work.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `sentinel-usage login` | Stores the token read from standard input, installs the Cursor hook and registers the startup task. If any step fails, nothing is left installed |
+| `sentinel-usage report` | Uploads the usage that is new since the last accepted day. Run by the startup task; safe to run by hand |
+| `sentinel-usage status` | Says whether the agent and the startup task are installed, which tool this connection reports, and the last accepted day. It does not print the token |
+| `sentinel-usage logout` | Removes the startup task, the Cursor hook and the token from this machine |
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Done, including "there is no new usage to upload" |
+| `2` | Wrong usage: unknown command, malformed token, or a base URL that is not `https` |
+| `3` | The startup task could not be registered or removed |
+| `4` | The server did not accept a day, or no longer recognizes the token |
+| `5` | Copilot: `gh` is missing or lacks permission to read the usage |
+
+Messages are printed in Spanish.
+
+## What actually leaves your machine
+
+One request per day of usage, with **the day, the model and the counters** — input, output,
+cache-read and cache-write tokens, and the number of turns — plus a random identifier generated
+on this machine that only tells two laptops apart.
+
+Not the prompt, not the code, not the conversation, not your email and not the path of a
+transcript. The CLI reads only the tool its connection is for: a connection enrolled for Cursor
+never opens a Claude Code transcript, and `gh` is not called unless the connection is Copilot.
+
+The figures are not converted to money and are not added to billed or estimated spend.
+
+## What is read, per tool
+
+- **Cursor.** A hook in `~/.cursor/hooks.json` writes one small file per turn to a local spool.
+  If the hook carries token counters they are reported per model; the stored input excludes
+  cache. If the counters are missing, the turn is counted and no token number is invented.
+- **Claude Code.** The usage counters of the local session files. A cost figure that sometimes
+  comes with the session is not uploaded. A turn here is one call to the model, so a reply that
+  uses tools counts several.
+- **GitHub Copilot.** Premium requests by model for the personal account, read through `gh`.
+  GitHub does not report tokens. This is account usage, not device usage, so two laptops do not
+  double it. The GitHub token is not read in order to send it. If `gh` answers 401 or 403, an
+  empty row is not written.
+- **Codex.** Session counters, only when Codex is signed in with the ChatGPT subscription. If its
+  auth file shows an API key, nothing is attributed to the individual account: that spend belongs
+  to the organization connection.
+
+Usage from before `login` is never uploaded: it predates the enrollment and the server would
+reject it.
+
+## Environment variables
+
+None is required.
+
+| Variable | Meaning |
+| --- | --- |
+| `SENTINEL_USAGE_BASE_URL` | Defaults to `https://api.aaa-sentinel.com`. Must be `https` — the token is never sent over plain HTTP |
+| `SENTINEL_USAGE_HOME` | Where the token, the state and the spool live. Defaults to `~/.config/aaa-sentinel` |
+| `SENTINEL_USAGE_CURSOR_HOOKS` | Path of Cursor's hooks file. Defaults to `~/.cursor/hooks.json` |
+| `SENTINEL_USAGE_CLAUDE_DIR` | Claude Code projects folder. Defaults to `projects` under `CLAUDE_CONFIG_DIR` or `~/.claude` |
+| `SENTINEL_USAGE_CODEX_HOME` | Codex folder. Defaults to `CODEX_HOME` or `~/.codex` |
+
+The token is stored in `usage.json` inside `SENTINEL_USAGE_HOME`, readable only by your user.
+
+## Troubleshooting
+
+**`sentinel-usage` is not found after installing.** Open a new terminal: the global `npm` folder
+is added to `PATH` when the shell starts.
+
+**`report` exits with 4 and says the server does not recognize the token.** The token was rotated
+or the connection was removed. Enroll again in the portal and repeat `login` with the new token.
+
+**`report` says the usage does not belong to this connection.** The token was enrolled for a
+different tool than the one in use on this machine. Nothing is uploaded; enroll the token from
+the connection that matches the tool.
+
+**The connection shows a silent agent in the portal.** The token exists and this renewal period
+has no usage yet. That is not a zero — use the tool and wait for the next hourly run, or run
+`sentinel-usage report` by hand.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The licence covers this client only; access to the API is governed by
+the terms of service at <https://app.aaa-sentinel.com>.