@hasna/economy 0.3.7 → 0.3.8

package/docs/configuration.md

@@ -0,0 +1,86 @@
+# Configuration and deployment
+
+## Local data
+
+The default data directory is `~/.hasna/economy/` and the SQLite database is `~/.hasna/economy/economy.db`. On first access, regular files in an older `~/.economy/` directory are copied when the new directory does not yet exist.
+
+| Variable | Effect |
+| --- | --- |
+| `HASNA_ECONOMY_DB_PATH` | SQLite path; takes precedence over `ECONOMY_DB`. |
+| `ECONOMY_DB` | Alternate SQLite path. `:memory:` is useful for tests. |
+| `HASNA_ECONOMY_CONFIG_PATH` | Path to `config.json`; defaults under the data directory. |
+| `ECONOMY_MACHINE_ID` | Machine identifier; otherwise Economy uses the normalized hostname. |
+| `ECONOMY_TAG` | Fallback attribution tag on locally written sessions/requests. |
+
+`economy config` reads and writes `config.json`. The defaults are `port=3456`, `default-period=today`, `auto-sync=true`, `sync-interval=30`, `alert-thresholds=[5,10,25,50,100]`, and `webhook-url=null`. At present, `webhook-url` drives budget notifications and `activeModel` drives `economy brains`; the other stored values are compatibility/settings metadata. Binary ports, periods, and watch intervals still come from command options or the environment described below.
+
+## Account attribution
+
+For an agent token such as `CODEX`, Economy checks these explicit forms before consulting `@hasna/accounts`:
+
+```text
+ECONOMY_CODEX_ACCOUNT_KEY or ECONOMY_CODEX_ACCOUNT
+ECONOMY_ACCOUNT_KEY       or ECONOMY_ACCOUNT
+```
+
+Values may be `tool:name` (for example `codex:work`) or a bare name/email. The structured form is:
+
+```text
+ECONOMY_CODEX_ACCOUNT_TOOL / _NAME / _EMAIL
+ECONOMY_ACCOUNT_TOOL       / _NAME / _EMAIL
+```
+
+The same agent-specific pattern applies to all eight supported agents. Account keys use the tool plus normalized email when available, otherwise the profile name.
+
+## CLI/MCP cloud client
+
+Local is the default. To route CLI and MCP data operations to a shared server, set:
+
+```bash
+export HASNA_ECONOMY_API_URL=https://economy.example.com
+export HASNA_ECONOMY_API_KEY='...'
+```
+
+URL plus key is itself a cloud-mode signal. You may explicitly set `HASNA_ECONOMY_STORAGE_MODE=cloud`; `self_hosted`, `remote`, and `hybrid` are accepted deprecated aliases. The resolver also accepts `HASNA_ECONOMY_MODE`, `ECONOMY_STORAGE_MODE`, and `ECONOMY_MODE`, plus unprefixed `ECONOMY_API_URL`/`ECONOMY_API_KEY` aliases. An existing `/v1` suffix is normalized, otherwise it is appended. Cloud mode with no key or an invalid URL fails rather than reading an unintended local dataset.
+
+In cloud-client mode, data commands use the HTTP API, and local auto-sync, explicit `economy sync`, and `economy billing sync` are skipped. Clients never need or use a Postgres DSN.
+
+## REST server
+
+Start the local server with either:
+
+```bash
+economy serve --port 3456
+economy-serve --port 3456
+```
+
+`ECONOMY_PORT` supplies the `economy-serve` default. `ECONOMY_BIND` (or `ECONOMY_HOST`) controls the local bind host. `ECONOMY_API_TOKEN` (or `HASNA_ECONOMY_API_TOKEN`) enables the local shared-token check; send it as `Authorization: Bearer ...` or `X-Economy-Token`.
+
+Without a local token, the current server defaults to `0.0.0.0` and API routes are unauthenticated. Set a token and an intentional bind address before exposing a local-mode server to another host.
+
+The server serves `dashboard/dist` and falls back to its `index.html` for non-API paths when those assets exist.
+
+## Self-hosted server
+
+The server switches to direct Postgres mode when `HASNA_ECONOMY_STORAGE_MODE=cloud` or when a DSN is present:
+
+```text
+HASNA_ECONOMY_DATABASE_URL
+ECONOMY_DATABASE_URL
+DATABASE_URL
+```
+
+Apply migrations with `economy-serve migrate`. `ECONOMY_PG_POOL_MAX` defaults to 5. A non-loopback cloud server also requires one of `HASNA_ECONOMY_API_SIGNING_KEY`, `HASNA_API_SIGNING_KEY`, or `API_KEY_SIGNING_SECRET`; API keys are then verified by `@hasna/contracts`. The signing secret belongs only on the server.
+
+See [REST API authentication](rest-api.md#authentication) for request headers and open probes.
+
+## Other services
+
+| Variable | Effect |
+| --- | --- |
+| `MCP_HTTP=1` | Run `economy-mcp` in Streamable HTTP mode instead of stdio. |
+| `MCP_HTTP_PORT` | MCP HTTP port; default 8860 and overridden by `--port`. |
+| `ECONOMY_OTEL_PORT` | OTLP sidecar port; default 4318 and overridden by `--port`. |
+| `ECONOMY_OTEL_BIND` | OTLP sidecar bind host; default `127.0.0.1`. |
+
+Source- and billing-specific environment variables are listed in [Ingestion](ingestion.md).

package/docs/ingestion.md

@@ -0,0 +1,47 @@
+# Ingestion
+
+`economy sync` imports local coding-agent usage into Economy's SQLite database. A sync with no source flag runs every source; one or more source flags limit the run. Reads such as `economy today` also auto-sync all local sources before querying.
+
+In cloud-client mode, CLI and MCP reads/writes go directly to the shared HTTP API. Local `sync` and `billing sync` deliberately do nothing in that mode; ingest on a machine running in local mode, or use the authenticated server ingest endpoints.
+
+## Sources
+
+| Source | Default input | Notes and overrides |
+| --- | --- | --- |
+| Claude Code | `~/.claude/projects/**/*.jsonl` | Imports assistant messages with usage, including cache tiers and supported pricing modifiers. Quota uses `~/.claude/.credentials.json`, `CLAUDE_OAUTH_TOKEN`, or `ANTHROPIC_OAUTH_TOKEN`. |
+| Takumi | `~/.takumi/projects/**/*.jsonl` | Uses the same JSONL ingestion format as Claude. |
+| Codex | `~/.codex/state_5.sqlite`, rollout JSONL, and `~/.codex/config.toml` | Overrides: `HASNA_ECONOMY_CODEX_DB_PATH`, `HASNA_ECONOMY_CODEX_CONFIG_PATH`. Quota uses `~/.codex/auth.json` or `CODEX_OAUTH_TOKEN`; `CODEX_USAGE_URL` can override the quota URL. |
+| Codewith (reported as Codex) | `~/.codewith/state_5.sqlite` and `~/.codewith/config.toml` | Overrides: `HASNA_ECONOMY_CODEWITH_DB_PATH`, `HASNA_ECONOMY_CODEWITH_CONFIG_PATH`. An explicit Codex DB path disables default Codewith discovery unless a Codewith DB path is also explicit. |
+| Gemini CLI | `~/.gemini/tmp` and `~/.gemini/history` | Overrides: `HASNA_ECONOMY_GEMINI_TMP_DIR`, `HASNA_ECONOMY_GEMINI_HISTORY_DIR`. |
+| OpenCode | `~/.local/share/opencode/storage/message/**/*.json` | Imports assistant-message usage and uses the recorded cost when present. |
+| Cursor | Cursor `/api/usage` and `/api/usage-summary` | Requires `CURSOR_SESSION_TOKEN` (or `CURSOR_API_TOKEN`). Creates daily usage snapshots and a subscription rollup when spend is present. |
+| Pi | `~/.pi/agent/sessions/**/*.json` | Override with `PI_CODING_AGENT_SESSION_DIR`. Uses recorded turn cost; a missing cost remains zero until pricing is repaired or the source records one. |
+| Hermes | `~/.hermes/state.db` | Imports session-level token and cost rollups. |
+| OpenLoops | `~/.hasna/loops/loops.db` | Override with `HASNA_ECONOMY_LOOPS_DB_PATH`; price with `HASNA_ECONOMY_LOOPS_MODEL` or `ECONOMY_LOOPS_MODEL`. Imports orchestration/judge `goal_runs.tokens_used` only, into `loop:*` cost centers. |
+
+Full, unfiltered sync also attempts to import active metadata from `@hasna/projects`. Missing files, optional registries, and unavailable quota credentials are skipped; use `--verbose` to see source-level diagnostics.
+
+## Incremental and repair behavior
+
+File/database state is cached in the `ingest_state` table, and request IDs are upserted and deduplicated. Consequently, normal repeated syncs are incremental.
+
+- `--force` clears the ingest-state entries for the supported sources and reprocesses them.
+- `--backfill-machine` fills empty `machine_id` values with `ECONOMY_MACHINE_ID` or the normalized hostname.
+- `--recalculate` prices token-bearing requests whose `cost_usd` is zero, then rerolls affected sessions. It reports buckets still missing usable pricing.
+- Budget webhooks are checked after a CLI or REST sync. Failed deliveries remain eligible for a later retry.
+
+## Account and cost-center attribution
+
+Economy first checks agent-specific overrides such as `ECONOMY_CODEX_ACCOUNT`, then generic `ECONOMY_ACCOUNT` overrides, then matching `@hasna/accounts` env-dir/applied/current profiles. An override may be `tool:name`, an email, or separate `*_ACCOUNT_TOOL`, `*_ACCOUNT_NAME`, and `*_ACCOUNT_EMAIL` fields. See [configuration](configuration.md#account-attribution).
+
+Apps and services can report explicit project, repository, account, attribution-tag, and cost-center fields through [`economy-otel`](otel.md). `ECONOMY_TAG` supplies a fallback attribution tag for records written through the local database helpers.
+
+## Provider billing
+
+`economy billing sync --days 31` imports ground-truth daily billing locally:
+
+- Anthropic: `HASNAXYZ_ANTHROPIC_LIVE_ADMIN_API_KEY` or `ANTHROPIC_ADMIN_API_KEY`.
+- OpenAI: `HASNAXYZ_OPENAI_LIVE_ADMIN_API_KEY` or `OPENAI_ADMIN_API_KEY`.
+- Gemini export: `HASNA_ECONOMY_GEMINI_BILLING_EXPORT_PATH`, `HASNAXYZ_ECONOMY_GEMINI_BILLING_EXPORT_PATH`, or `GEMINI_BILLING_EXPORT_PATH`.
+
+Gemini imports JSON arrays, objects with a `rows` array, JSONL, or simple CSV. `economy billing show` compares totals; `economy billing diff` applies the reconciliation threshold.

package/docs/mcp.md

@@ -0,0 +1,65 @@
+# MCP server
+
+`economy-mcp` uses stdio by default:
+
+```bash
+claude mcp add --transport stdio --scope user economy -- economy-mcp
+```
+
+Codex configuration:
+
+```toml
+[mcp_servers.economy]
+command = "economy-mcp"
+args = []
+```
+
+Gemini settings:
+
+```json
+{
+  "mcpServers": {
+    "economy": { "command": "economy-mcp", "args": [] }
+  }
+}
+```
+
+`economy mcp --all` prints these snippets. The MCP server uses the same local-versus-cloud Store selection as the CLI; configure a shared API with `HASNA_ECONOMY_API_URL` and `HASNA_ECONOMY_API_KEY` as described in [configuration](configuration.md#climcp-cloud-client).
+
+## Streamable HTTP
+
+```bash
+economy-mcp --http                 # http://127.0.0.1:8860/mcp
+MCP_HTTP=1 economy-mcp             # same
+economy-mcp --http --port 8815
+```
+
+`MCP_HTTP_PORT` supplies the default HTTP port. The transport binds to loopback, exposes `POST /mcp`, and exposes `GET /health`. Stdio remains the default when `--http`/`MCP_HTTP` is absent.
+
+## Tools
+
+Discovery helpers:
+
+- `search_tools`, `describe_tools`
+
+Cost and activity reads:
+
+- `get_cost_summary`, `get_sessions`, `get_session_detail`, `get_top_sessions`
+- `get_model_breakdown`, `get_project_breakdown`, `get_agent_breakdown`, `get_account_breakdown`, `get_cost_center_breakdown`
+- `get_daily`, `list_machines`, `get_usage`, `get_savings`, `get_billing_summary`
+
+Management and estimation:
+
+- `get_budget_status`, `set_budget`, `remove_budget`
+- `get_goals`, `set_goal`, `remove_goal`
+- `get_pricing`, `set_pricing`, `remove_pricing`, `estimate_cost`
+- `list_subscriptions`, `set_subscription`, `remove_subscription`
+- `sync`, `send_feedback`
+
+Shared agent-registry tools:
+
+- `register_agent`, `heartbeat`, `set_focus`, `list_agents`
+
+High-cardinality tools return compact text by default. Where the schema offers them, use `limit`, `verbose=true`, or `json=true`. Limits are clamped to 100 for MCP calls.
+
+The `sync` tool accepts `all`, any supported coding agent, or `loops`. It ingests on-box files only in local mode. In cloud-client mode it returns an explanatory no-op because all other data tools already use the shared API.

package/docs/otel.md

@@ -0,0 +1,53 @@
+# OTLP/HTTP sidecar
+
+`economy-otel` writes application/service metrics into the local Economy SQLite database:
+
+```bash
+economy-otel --port 4318
+```
+
+It binds to `127.0.0.1` by default. Override the bind with `ECONOMY_OTEL_BIND` and the port with `ECONOMY_OTEL_PORT` or `--port`.
+
+| Method | Path | Behavior |
+| --- | --- | --- |
+| `GET` | `/health` | `{ status, service, version }`. |
+| `POST` | `/v1/metrics` | Parse an OTLP JSON `resourceMetrics` payload. |
+| `POST` | `/ingest` | Parse one simplified JSON cost/token event. |
+
+Other methods return 405. Invalid JSON returns 400. A valid payload with no recognized positive cost/token metrics returns `{ "ingested": 0, "message": "no matching metrics" }`.
+
+## Simplified event
+
+```bash
+curl -X POST http://127.0.0.1:4318/ingest \
+  -H 'content-type: application/json' \
+  -d '{
+    "source": "app",
+    "cost_center": "alumia",
+    "cost_center_kind": "app",
+    "project_path": "/workspace/alumia",
+    "model": "gpt-5-mini",
+    "cost_usd": 0.12,
+    "input_tokens": 1200,
+    "output_tokens": 300
+  }'
+```
+
+Core fields are `agent`/`source`, `session_id`, `request_id` or `source_request_id`, `model`, `timestamp`, `cost_usd`, `input_tokens`, and `output_tokens`. An event must have positive cost or tokens.
+
+Attribution fields include:
+
+- `cost_center`, `cost_center_kind`, `cost_center_id`
+- `attribution_tag`, `project_path`, `project_name`, `repo`
+- `account_key`, `account_tool`, `account_name`, `account_email`, `account_source`
+- `cost_basis` (`metered_api`, `subscription_included`, `estimated`, or `unknown`)
+
+Cost-center kinds are `loop`, `app`, `repo`, `service`, and `team`. When kind and name are present, the sidecar creates a cost center such as `app:alumia` unless an explicit ID is supplied. Unknown agents normalize to the cost-center kind when it is a supported pseudo-agent (`app`, `service`, `repo`, `loop`), otherwise `service`.
+
+## OTLP recognition
+
+The OTLP parser reads sum or gauge data points. Metric names containing cost or `.usd` become cost; names containing input+token or `tokens.input` become input tokens; names containing output+token or `tokens.output` become output tokens. Points are joined by agent and request/event ID.
+
+Resource and point attributes may use plain names (`model`, `session_id`, `request_id`, `project_path`, and the attribution fields above) or common dotted aliases such as `ai.model`, `session.id`, `event.id`, `service.name`, `economy.cost_center`, and `account.email`.
+
+The sidecar always opens the local SQLite database. It does not forward to a cloud API; use the authenticated REST bulk-ingest path for remote ingestion.

package/docs/rest-api.md

@@ -0,0 +1,89 @@
+# REST API
+
+Start the service with `economy-serve` or `economy serve`. The default local origin is `http://127.0.0.1:3456`; the bind behavior is detailed in [configuration](configuration.md#rest-server).
+
+The canonical application prefix is `/v1`. Equivalent `/api` routes remain available for the bundled dashboard and older clients. Successful application responses use:
+
+```json
+{ "data": {}, "meta": {} }
+```
+
+Errors use `{ "error": "message" }`. Foundation probes return a direct `{ status, version, mode, service }` object instead of the data envelope.
+
+## Discovery and probes
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/health`, `/healthz` | Liveness. |
+| `GET` | `/ready`, `/readyz` | Storage readiness; may return 503. |
+| `GET` | `/version`, `/v1/version` | Version and deployment mode. |
+| `GET` | `/openapi.json` | Runtime-versioned OpenAPI document. |
+
+These routes are open. The checked-in OpenAPI source is [`openapi/economy.json`](../openapi/economy.json).
+
+## Authentication
+
+In local mode, set `ECONOMY_API_TOKEN` or `HASNA_ECONOMY_API_TOKEN` and send either:
+
+```text
+Authorization: Bearer <token>
+X-Economy-Token: <token>
+```
+
+In self-hosted Postgres mode, send a valid Economy API key as `x-api-key` or a bearer token. All non-probe routes require a valid key when the server has an authenticator. Bulk ingest and feedback additionally request the `economy:write` scope.
+
+## Read routes
+
+| Method | Canonical path | Parameters/behavior |
+| --- | --- | --- |
+| `GET` | `/v1/summary` | `period` (default `today`), optional `machine`. |
+| `GET` | `/v1/machines` | Machine rollups and current machine metadata. |
+| `GET` | `/v1/fleet` | `period` (default `month`), optional `machine`; returns summary, machines, registry. |
+| `GET` | `/v1/daily` | `days` (default 30), optional `machine`. |
+| `GET` | `/v1/hourly` | Optional `machine`; `hours` must be 1–48. |
+| `GET` | `/v1/sessions` | `agent`, `project`, `search`, `machine`, `account`, `limit` (50), `offset` (0), `since`, and comma-separated `fields`. |
+| `GET` | `/v1/sessions/{id}/requests` | Full ID or unique prefix; returns 404 when absent. |
+| `GET` | `/v1/top` | `n` (default 10), optional `agent` and `since`. |
+| `GET` | `/v1/models` | Model breakdown. |
+| `GET` | `/v1/projects` | Project breakdown; `period` defaults to `all`, optional `machine`. |
+| `GET` | `/v1/projects/detail` | Detailed project query; `q` is required. |
+| `GET` | `/v1/accounts` | Account breakdown; `period` defaults to `all`, optional `machine`. |
+| `GET` | `/v1/breakdown` | `by=model|project|agent|account|cost-center|loop|app|repo|service|team`, optional `period` and `machine`. |
+| `GET` | `/v1/usage` | `period` (default `month`), optional valid `agent`. |
+| `GET` | `/v1/savings` | `period` (default `month`), optional valid `agent`. |
+| `GET` | `/v1/billing` | `period` (default `month`). |
+| `GET` | `/v1/billing/diff` | `period` (default `month`), `threshold` percentage (default 15). |
+| `GET` | `/v1/budgets` | Budget statuses. |
+| `GET` | `/v1/goals` | Goal statuses. |
+| `GET` | `/v1/pricing` | Model pricing rows. |
+| `GET` | `/v1/subscriptions` | Subscription plans. |
+| `GET` | `/v1/project-registry` | Registered projects. |
+| `GET` | `/v1/brief` | Fleet brief; optional `since` and `machine`. |
+| `GET` | `/v1/export` | `type=sessions|requests`, `period` (default `month`); returns rows in JSON for clients to encode. |
+| `GET` | `/v1/compare` | Required `from` and `to` dates (`YYYY-MM-DD`). |
+| `GET` | `/v1/forecast` | Current-month projection. |
+| `GET` | `/v1/efficiency` | Per-model token efficiency. |
+| `GET` | `/v1/requests` | Requests after required ISO `since`; used by live watch. |
+
+Common period values are `today`, `yesterday`, `week`, `month`, `year`, and `all`, but individual routes accept the subset documented above.
+
+## Mutation routes
+
+| Method | Canonical path | Body/behavior |
+| --- | --- | --- |
+| `POST` | `/v1/budgets` | Positive `limit_usd`; optional `period`, `alert_at_percent`, `project_path`, `agent`, `cost_center_id`. |
+| `DELETE` | `/v1/budgets/{id}` | Delete a budget. |
+| `POST` | `/v1/goals` | Positive `limit_usd`; `period=day|week|month|year`; optional `project_path`, `agent`. |
+| `DELETE` | `/v1/goals/{id}` | Delete a goal. |
+| `POST` | `/v1/pricing` | `model`, non-negative input/output/cache pricing fields. |
+| `DELETE` | `/v1/pricing/{model}` | Delete a URL-encoded model row. |
+| `POST` | `/v1/subscriptions` | Required `provider` and `plan`; optional ID, agent, fee/inclusion, cycle/reset, and active fields. |
+| `DELETE` | `/v1/subscriptions/{id}` | Delete a plan. |
+| `POST` | `/v1/project-registry` | Required `path`; optional `name`, `description`, `tags`. |
+| `DELETE` | `/v1/project-registry/{path}` | Delete a URL-encoded project path. |
+| `POST` | `/v1/sync` | `{ "sources": "all" }` or one of the eight agents/`loops`; triggers server-local ingestion. |
+| `POST` | `/v1/billing/sync` | Optional `days` (1–366) and `providers` from `anthropic`, `openai`, `gemini`. Provider failures are returned per provider. |
+| `POST` | `/v1/ingest` | Idempotently merge arrays named `requests`, `sessions`, `projects`, `budgets`, `goals`, `billing_daily`, `model_pricing`, `subscriptions`, and `usage_snapshots`. |
+| `POST` | `/v1/feedback` | Required `message`; optional `email` and `category=bug|feature|general`. |
+
+Agent fields accept `claude`, `takumi`, `codex`, `gemini`, `opencode`, `cursor`, `pi`, or `hermes`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/economy",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "AI coding cost tracker — CLI + MCP server + REST API + web dashboard for Claude Code, Codex, Gemini, OpenCode, Cursor, Pi, and Hermes",
   "repository": {
     "type": "git",
@@ -27,6 +27,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "dashboard/dist",
     "LICENSE",
     "README.md",
@@ -69,13 +70,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@hasna/accounts": "0.1.6",
+    "@hasna/accounts": "0.2.23",
     "@hasna/agent-registry": "^0.1.0",
-    "@hasna/cloud": "0.1.24",
     "@hasna/contracts": "^0.4.2",
     "@hasna/events": "^0.1.7",
     "@hasna/mcp-harness": "^0.1.0",
-    "@hasna/projects": "0.1.51",
+    "@hasna/projects": "0.1.95",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
@@ -89,7 +89,6 @@
     "typescript": "^5.7.2"
   },
   "trustedDependencies": [
-    "@hasna/cloud",
     "@hasna/projects"
   ]
 }