@aiaiai-pt/martha-cli 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [0.63.0] — 2026-10-09
+
+### Added — spend ceilings narrowed by API Client (#1635)
+
+A ceiling covers the tenant, narrowed to an AI Agent and/or an API Client. It
+applies to a call when every dimension it names matches, so one AI Agent can be
+capped within one API Client.
+
+- `martha budget set --client <id>` (combine with `--agent <uuid>` for an agent within a client).
+- `martha budget list` names each ceiling's scope: `tenant`, `agent <name>`,
+  `client <name>`, or `agent <name> via client <name>`.
+- `martha spend --group-by client`: spend per API Client.
+
 ## [0.62.0] — 2026-10-08
 
 ### Added — `--org` picks the organization for multi-organization tokens (#1611)

package/dist/index.js

@@ -11244,7 +11244,7 @@ init_config();
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.62.0";
+var CLI_VERSION = "0.63.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -21744,7 +21744,7 @@ ${models.length} models`));
 
 // src/commands/spend.ts
 init_errors();
-var GROUPINGS = ["day", "agent", "model", "surface", "billing_owner"];
+var GROUPINGS = ["day", "agent", "model", "surface", "billing_owner", "client"];
 function usd(value) {
   return value == null ? "-" : `$${Number(value).toFixed(4)}`;
 }
@@ -21803,6 +21803,13 @@ ${data.tenant_id}: ${t.calls} calls, ${usd(t.cost_usd)}` + (t.unpriced_calls ? `
 init_errors();
 var PERIODS = ["day", "month"];
 var ACTIONS = ["warn", "require_approval", "block"];
+function budgetScope(b) {
+  const agent = b.agent_id ? `agent ${b.agent_name ?? b.agent_id}` : null;
+  const client = b.client_id ? `client ${b.client_name ?? b.client_id}` : null;
+  if (agent && client)
+    return `${agent} via ${client}`;
+  return agent ?? client ?? "tenant";
+}
 function oneOf(value, allowed, flag) {
   if (!allowed.includes(value)) {
     throw new CLIError(`${flag} must be one of: ${allowed.join(", ")}`, 4 /* Validation */);
@@ -21832,22 +21839,25 @@ function registerBudgetCommands(program) {
       return;
     }
     for (const b of data.budgets) {
-      const scope = b.agent_id ? `agent ${b.agent_id}` : "tenant";
-      console.log(`${b.id}  ${scope.padEnd(42)} ${b.period.padEnd(6)} $${b.limit_usd}  ${b.action}`);
+      console.log(`${b.id}  ${budgetScope(b).padEnd(42)} ${b.period.padEnd(6)} $${b.limit_usd}  ${b.action}`);
     }
   });
-  budget.command("set").description("Create or replace a ceiling (one per tenant-or-agent + period)").requiredOption("--period <p>", `One of: ${PERIODS.join(", ")}`).requiredOption("--limit <usd>", "Ceiling in USD (cache reads included)").requiredOption("--action <a>", `One of: ${ACTIONS.join(", ")}`).option("--agent <uuid>", "Scope to one AI Agent (default: whole tenant)").option("--note <text>", "Why this ceiling exists").option("--tenant <id>", "Tenant (defaults to your own)").action(async (opts) => {
+  budget.command("set").description("Create or replace a ceiling (one per scope + period)").requiredOption("--period <p>", `One of: ${PERIODS.join(", ")}`).requiredOption("--limit <usd>", "Ceiling in USD (cache reads included)").requiredOption("--action <a>", `One of: ${ACTIONS.join(", ")}`).option("--agent <uuid>", "Narrow to one AI Agent (default: whole tenant)").option("--client <id>", "Narrow to one API Client (with --agent: that agent within it)").option("--note <text>", "Why this ceiling exists").option("--tenant <id>", "Tenant (defaults to your own)").action(async (opts) => {
     oneOf(opts.period, PERIODS, "--period");
     oneOf(opts.action, ACTIONS, "--action");
     if (!/^\d+(\.\d{1,4})?$/.test(opts.limit)) {
       throw new CLIError("--limit must be a non-negative USD amount", 4 /* Validation */);
     }
+    if (opts.client !== undefined && !/^[1-9]\d*$/.test(opts.client)) {
+      throw new CLIError("--client must be an API Client id (a positive integer)", 4 /* Validation */);
+    }
     const ctx = context();
     const saved = await ctx.api.put(await path(ctx, opts.tenant), {
       period: opts.period,
       limit_usd: opts.limit,
       action: opts.action,
       agent_id: opts.agent ?? null,
+      client_id: opts.client !== undefined ? Number(opts.client) : null,
       note: opts.note ?? null
     });
     if (program.opts().json)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {