@hasna/economy 0.2.22 → 0.2.23

package/README.md

@@ -1,15 +1,16 @@
 # @hasna/economy
 
-AI coding cost tracker for Claude Code, Takumi, Codex, and Gemini. It ships as a CLI, MCP server, REST API, web dashboard, and native macOS menu bar app.
+AI coding cost tracker for Claude Code, Takumi, Codex, Gemini, OpenCode, Cursor, Pi, and Hermes. It ships as a CLI, MCP server, REST API, web dashboard, and native macOS menu bar app.
 
 [![npm](https://img.shields.io/npm/v/@hasna/economy)](https://www.npmjs.com/package/@hasna/economy)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 
 ## Features
 
-- Ingests local Claude Code, Takumi, Codex, and Gemini CLI usage.
+- Ingests local Claude Code, Takumi, Codex, Gemini, OpenCode, Cursor, Pi, and Hermes usage.
 - Tracks sessions, requests, projects, machines, models, cache tokens, budgets, goals, and provider billing.
 - Attributes usage to `@hasna/accounts` profiles when agents run under managed account/profile config dirs.
+- Breaks down API-equivalent, metered API, subscription-included, estimated, and unknown cost by account and coding agent.
 - Seeds editable model pricing with input, output, cache-read, 5-minute cache-write, 1-hour cache-write, and context-cache storage rates.
 - Handles tiered pricing such as Gemini long-prompt rates and OpenAI long-context rates.
 - Reconciles estimates against Anthropic, OpenAI, and Gemini billing sources.
@@ -70,7 +71,7 @@ Gemini settings:
 }
 ```
 
-The MCP server exposes read tools for summaries, sessions, machines, pricing, daily spend, budgets, goals, and provider billing. It also exposes mutation tools for budgets, pricing rows, and goals so Claude Code, Codex, and Gemini can manage Economy data through the same validated surface as the CLI and REST API.
+The MCP server exposes read tools for summaries, sessions, machines, pricing, daily spend, budgets, goals, provider billing, usage snapshots, savings, project/account/agent breakdowns, and subscriptions. It also exposes mutation tools for budgets, pricing rows, goals, and subscriptions so coding agents can manage Economy data through the same validated surface as the CLI and REST API.
 
 ## Ingest
 
@@ -87,6 +88,10 @@ economy sync --claude
 economy sync --codex
 economy sync --gemini
 economy sync --takumi
+economy sync --opencode
+economy sync --cursor
+economy sync --pi
+economy sync --hermes
 ```
 
 Useful repair options:
@@ -103,6 +108,15 @@ Account attribution is automatic when `@hasna/accounts` has a matching active, a
 
 Account breakdowns report `api_equivalent_usd` for the API list-price value of the usage, plus `billable_usd`/`metered_api_usd` for known direct API spend and `subscription_included_usd` for usage covered by a subscription.
 
+Subscription plans can be configured locally and are used by savings calculations:
+
+```bash
+economy subscriptions set --provider cursor --plan pro --fee 20 --included 20 --agent cursor
+economy subscriptions list
+economy savings month
+economy usage month --agent cursor
+```
+
 ## Pricing
 
 Default pricing is seeded into SQLite and can be edited locally:
@@ -150,7 +164,7 @@ economy config set webhook-url https://example.com/economy-webhook
 economy config webhook-test
 ```
 
-Budgets and goals can be global, project-scoped with `--project`, agent-scoped with `--agent`, or both. Valid agent scopes are `claude`, `takumi`, `codex`, and `gemini`.
+Budgets and goals can be global, project-scoped with `--project`, agent-scoped with `--agent`, or both. Valid agent scopes are `claude`, `takumi`, `codex`, `gemini`, `opencode`, `cursor`, `pi`, and `hermes`.
 
 Budget webhooks fire after sync when the alert threshold is crossed. Failed webhook deliveries are not marked as fired, so the next sync can retry them.
 
@@ -169,7 +183,14 @@ Common endpoints:
 - `GET /api/sessions?agent=codex&limit=20`
 - `GET /api/sessions/:id/requests`
 - `GET /api/models`
-- `GET /api/projects`
+- `GET /api/projects?period=month`
+- `GET /api/breakdown?by=agent&period=month`
+- `GET /api/accounts?period=month`
+- `GET /api/usage?period=month`
+- `GET /api/savings?period=month`
+- `GET /api/subscriptions`
+- `POST /api/subscriptions`
+- `DELETE /api/subscriptions/:id`
 - `GET /api/budgets`
 - `POST /api/budgets`
 - `DELETE /api/budgets/:id`
@@ -183,13 +204,13 @@ Common endpoints:
 - `POST /api/sync`
 - `POST /api/billing/sync`
 
-Budget and goal mutation endpoints validate agent scopes against `claude`, `takumi`, `codex`, and `gemini`.
+Budget, goal, and subscription mutation endpoints validate agent scopes against `claude`, `takumi`, `codex`, `gemini`, `opencode`, `cursor`, `pi`, and `hermes`.
 
 The server also serves the built dashboard when `dashboard/dist` is present.
 
 ## Native macOS Menubar
 
-The `menubar/` app is a native SwiftUI `MenuBarExtra` app, not Electron. It targets Swift 5.9+ and macOS 14+, and talks to the REST API exposed by `economy-serve`. The default server URL is `http://127.0.0.1:3456`.
+The `menubar/` app is a native SwiftUI `MenuBarExtra` app, not Electron. It targets Swift 5.9+ and macOS 14+, and talks to the REST API exposed by `economy-serve`. It shows today/week/month spend, token and request counts, top agents, top accounts, top projects, subscription savings, usage snapshots, recent sessions, and fleet status. The default server URL is `http://127.0.0.1:3456`.
 
 Build it on macOS:
 

package/dist/cli/index.js

@@ -4574,6 +4574,50 @@ function createHandler(db) {
       const agent = url.searchParams.get("agent") ?? undefined;
       return ok(querySavingsSummary(db, period, agent && isAgent(agent) ? agent : undefined));
     }
+    if (path === "/api/subscriptions" && method === "GET") {
+      return ok(listSubscriptions(db));
+    }
+    if (path === "/api/subscriptions" && method === "POST") {
+      const body = await jsonBody(req);
+      if (!body)
+        return err("invalid JSON body");
+      const provider = optionalString(body["provider"])?.trim();
+      const plan = optionalString(body["plan"])?.trim();
+      if (!provider)
+        return err("provider is required");
+      if (!plan)
+        return err("plan is required");
+      const monthlyFee = finiteNumber(body["monthly_fee_usd"] ?? body["fee_usd"] ?? 0);
+      const includedUsage = finiteNumber(body["included_usage_usd"] ?? 0);
+      if (monthlyFee == null || monthlyFee < 0)
+        return err("monthly_fee_usd must be a non-negative number");
+      if (includedUsage == null || includedUsage < 0)
+        return err("included_usage_usd must be a non-negative number");
+      const agent = optionalAgent(body["agent"]);
+      if (agent === undefined)
+        return err(AGENT_ERROR);
+      const now = new Date().toISOString();
+      const subscription = {
+        id: optionalString(body["id"])?.trim() || randomUUID2(),
+        agent,
+        provider,
+        plan,
+        monthly_fee_usd: monthlyFee,
+        included_usage_usd: includedUsage,
+        billing_cycle_start: optionalString(body["billing_cycle_start"]),
+        reset_policy: optionalString(body["reset_policy"]) ?? "monthly",
+        active: body["active"] === false || body["active"] === 0 ? 0 : 1,
+        created_at: optionalString(body["created_at"]) ?? now,
+        updated_at: now
+      };
+      upsertSubscription(db, subscription);
+      return ok(subscription);
+    }
+    const subscriptionMatch = path.match(/^\/api\/subscriptions\/(.+)$/);
+    if (subscriptionMatch && method === "DELETE") {
+      deleteSubscription(db, decodeURIComponent(subscriptionMatch[1]));
+      return ok({ ok: true });
+    }
     const sessionRequestsMatch = path.match(/^\/api\/sessions\/([^/]+)\/requests$/);
     if (sessionRequestsMatch && method === "GET") {
       const sessionId = decodeURIComponent(sessionRequestsMatch[1]);

package/dist/mcp/index.js

@@ -1343,6 +1343,12 @@ function upsertSubscription(db, sub) {
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(sub.id, sub.agent, sub.provider, sub.plan, sub.monthly_fee_usd, sub.included_usage_usd, sub.billing_cycle_start, sub.reset_policy, sub.active, sub.created_at, sub.updated_at);
 }
+function listSubscriptions(db) {
+  return db.prepare(`SELECT * FROM subscriptions ORDER BY provider, plan`).all();
+}
+function deleteSubscription(db, id) {
+  db.prepare(`DELETE FROM subscriptions WHERE id = ?`).run(id);
+}
 function upsertUsageSnapshot(db, snap) {
   const now = snap.updated_at ?? new Date().toISOString();
   const id = snap.id ?? `${snap.agent}-${snap.date}-${snap.metric}-${snap.machine_id}`;
@@ -3314,6 +3320,9 @@ var TOOL_NAMES = [
   "get_session_detail",
   "get_usage",
   "get_savings",
+  "list_subscriptions",
+  "set_subscription",
+  "remove_subscription",
   "estimate_cost",
   "sync",
   "search_tools",
@@ -3348,6 +3357,9 @@ var TOOL_DESCRIPTIONS = {
   get_session_detail: "session_id(prefix ok) -> per-request breakdown with model, tokens, cost",
   get_usage: `period(today|week|month), agent?(${AGENTS.join("|")}) -> usage snapshots and all-machine summary`,
   get_savings: `period(today|week|month|year|all), agent?(${AGENTS.join("|")}) -> subscription/API-equivalent savings`,
+  list_subscriptions: "no params -> configured subscription plans and included usage",
+  set_subscription: `provider, plan, monthly_fee_usd?, included_usage_usd?, agent?(${AGENTS.join("|")}) -> create/update subscription plan`,
+  remove_subscription: "id -> delete subscription plan",
   estimate_cost: "model, input_tokens?, output_tokens? -> pre-flight token cost estimate",
   sync: `sources(all|${AGENTS.join("|")}) -> ingest latest cost data`,
   search_tools: "query substring -> tool name list",
@@ -3608,6 +3620,57 @@ server.tool("get_usage", "Usage snapshots and fleet summary. period: today|week|
 server.tool("get_savings", "Subscription vs API savings summary", { period: z.enum(["today", "week", "month", "year", "all"]).optional(), agent: z.enum(AGENTS).optional() }, async ({ period, agent }) => {
   return text(JSON.stringify(querySavingsSummary(db, period ?? "month", agent), null, 2));
 });
+server.tool("list_subscriptions", "List configured subscription plans and included usage caps. No params.", {}, async () => {
+  const rows = listSubscriptions(db);
+  if (rows.length === 0)
+    return text("No subscriptions configured.");
+  const lines = ["id       provider     plan        agent      fee       included  active"];
+  for (const row of rows) {
+    lines.push(`${String(row["id"]).slice(0, 8).padEnd(9)}` + `${String(row["provider"]).slice(0, 12).padEnd(13)}` + `${String(row["plan"]).slice(0, 10).padEnd(11)}` + `${String(row["agent"] ?? "all").slice(0, 10).padEnd(11)}` + `${fmtUsd(Number(row["monthly_fee_usd"] ?? 0)).padEnd(10)}` + `${fmtUsd(Number(row["included_usage_usd"] ?? 0)).padEnd(10)}` + `${Number(row["active"] ?? 0) ? "yes" : "no"}`);
+  }
+  return text(lines.join(`
+`));
+});
+server.tool("set_subscription", `Create or update a subscription plan. agent may be ${AGENTS.join("|")}.`, {
+  id: z.string().optional(),
+  provider: z.string(),
+  plan: z.string(),
+  agent: z.enum(AGENTS).optional(),
+  monthly_fee_usd: z.number().optional(),
+  included_usage_usd: z.number().optional(),
+  billing_cycle_start: z.string().optional(),
+  reset_policy: z.string().optional(),
+  active: z.boolean().optional()
+}, async (input) => {
+  if (input.monthly_fee_usd != null && input.monthly_fee_usd < 0)
+    return text("monthly_fee_usd must be non-negative");
+  if (input.included_usage_usd != null && input.included_usage_usd < 0)
+    return text("included_usage_usd must be non-negative");
+  const now = new Date().toISOString();
+  const subscription = {
+    id: input.id?.trim() || randomUUID(),
+    agent: input.agent ?? null,
+    provider: input.provider.trim(),
+    plan: input.plan.trim(),
+    monthly_fee_usd: input.monthly_fee_usd ?? 0,
+    included_usage_usd: input.included_usage_usd ?? 0,
+    billing_cycle_start: input.billing_cycle_start ?? null,
+    reset_policy: input.reset_policy ?? "monthly",
+    active: input.active === false ? 0 : 1,
+    created_at: now,
+    updated_at: now
+  };
+  if (!subscription.provider)
+    return text("provider is required");
+  if (!subscription.plan)
+    return text("plan is required");
+  upsertSubscription(db, subscription);
+  return text(JSON.stringify(subscription, null, 2));
+});
+server.tool("remove_subscription", "Remove a subscription plan by id.", { id: z.string() }, async ({ id }) => {
+  deleteSubscription(db, id);
+  return text(`Removed subscription ${id}`);
+});
 server.tool("estimate_cost", "Pre-flight cost estimate for token counts", { model: z.string(), input_tokens: z.number().optional(), output_tokens: z.number().optional() }, async ({ model, input_tokens, output_tokens }) => {
   const cost = computeCostFromDb(db, model, input_tokens ?? 0, output_tokens ?? 0, 0, 0, 0);
   return text(`${model}: ${fmtUsd(cost)} (${input_tokens ?? 0} in / ${output_tokens ?? 0} out)`);

package/dist/server/index.js

@@ -1364,6 +1364,12 @@ function upsertSubscription(db, sub) {
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(sub.id, sub.agent, sub.provider, sub.plan, sub.monthly_fee_usd, sub.included_usage_usd, sub.billing_cycle_start, sub.reset_policy, sub.active, sub.created_at, sub.updated_at);
 }
+function listSubscriptions(db) {
+  return db.prepare(`SELECT * FROM subscriptions ORDER BY provider, plan`).all();
+}
+function deleteSubscription(db, id) {
+  db.prepare(`DELETE FROM subscriptions WHERE id = ?`).run(id);
+}
 function upsertUsageSnapshot(db, snap) {
   const now = snap.updated_at ?? new Date().toISOString();
   const id = snap.id ?? `${snap.agent}-${snap.date}-${snap.metric}-${snap.machine_id}`;
@@ -4112,6 +4118,50 @@ function createHandler(db) {
       const agent = url.searchParams.get("agent") ?? undefined;
       return ok(querySavingsSummary(db, period, agent && isAgent(agent) ? agent : undefined));
     }
+    if (path === "/api/subscriptions" && method === "GET") {
+      return ok(listSubscriptions(db));
+    }
+    if (path === "/api/subscriptions" && method === "POST") {
+      const body = await jsonBody(req);
+      if (!body)
+        return err("invalid JSON body");
+      const provider = optionalString(body["provider"])?.trim();
+      const plan = optionalString(body["plan"])?.trim();
+      if (!provider)
+        return err("provider is required");
+      if (!plan)
+        return err("plan is required");
+      const monthlyFee = finiteNumber(body["monthly_fee_usd"] ?? body["fee_usd"] ?? 0);
+      const includedUsage = finiteNumber(body["included_usage_usd"] ?? 0);
+      if (monthlyFee == null || monthlyFee < 0)
+        return err("monthly_fee_usd must be a non-negative number");
+      if (includedUsage == null || includedUsage < 0)
+        return err("included_usage_usd must be a non-negative number");
+      const agent = optionalAgent(body["agent"]);
+      if (agent === undefined)
+        return err(AGENT_ERROR);
+      const now = new Date().toISOString();
+      const subscription = {
+        id: optionalString(body["id"])?.trim() || randomUUID(),
+        agent,
+        provider,
+        plan,
+        monthly_fee_usd: monthlyFee,
+        included_usage_usd: includedUsage,
+        billing_cycle_start: optionalString(body["billing_cycle_start"]),
+        reset_policy: optionalString(body["reset_policy"]) ?? "monthly",
+        active: body["active"] === false || body["active"] === 0 ? 0 : 1,
+        created_at: optionalString(body["created_at"]) ?? now,
+        updated_at: now
+      };
+      upsertSubscription(db, subscription);
+      return ok(subscription);
+    }
+    const subscriptionMatch = path.match(/^\/api\/subscriptions\/(.+)$/);
+    if (subscriptionMatch && method === "DELETE") {
+      deleteSubscription(db, decodeURIComponent(subscriptionMatch[1]));
+      return ok({ ok: true });
+    }
     const sessionRequestsMatch = path.match(/^\/api\/sessions\/([^/]+)\/requests$/);
     if (sessionRequestsMatch && method === "GET") {
       const sessionId = decodeURIComponent(sessionRequestsMatch[1]);

package/dist/server/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/server/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,cAAc,CAAA;AAqC7D,UAAU,kBAAkB;IAC1B,EAAE,CAAC,EAAE,QAAQ,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC;AAqED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,YAAY,SAAwB,IACzF,KAAK,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAwB7D;AAQD,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,IACV,KAAK,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAuT/D;AAED,wBAAgB,WAAW,CAAC,IAAI,SAAO,EAAE,OAAO,GAAE,kBAAuB,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAcvG"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/server/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,cAAc,CAAA;AAsC7D,UAAU,kBAAkB;IAC1B,EAAE,CAAC,EAAE,QAAQ,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC;AAqED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,YAAY,SAAwB,IACzF,KAAK,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAwB7D;AAQD,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,IACV,KAAK,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAgW/D;AAED,wBAAgB,WAAW,CAAC,IAAI,SAAO,EAAE,OAAO,GAAE,kBAAuB,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAcvG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/economy",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "AI coding cost tracker — CLI + MCP server + REST API + web dashboard for Claude Code, Codex, Gemini, OpenCode, Cursor, Pi, and Hermes",
   "type": "module",
   "main": "dist/index.js",