/iblai-vibe-agent-billing

Mirrored from iblai/vibe · skills/agents/iblai-vibe-agent-billing/SKILL.md. This page is generated — edit it in the repository, not here.

Add the agent Billing tab -- set LLM spend limits for this agent and its users, and see how much has been used. Two sub-tabs match the backend's agent-level scopes: This Agent (the agent's own spend cap) and Per User (explicit per-user limits on this agent, with the user picked through a platform-user search). Each limit has an enable toggle, a usage bar (spent / % used / remaining), a spend amount with a reset interval (day/week/month/year), an enforcement mode (Block Requests or Alert Only), and comma-separated alert thresholds at which admins get a near-limit alert. Enforcement is server-side — a blocked request is refused with a 429 / spend_cap_exceeded error until the period resets. This is one tab in the wider agent-settings family. All tabs share the same AgentSettingsProvider wrapper.

Common setup (brand, conventions, env files, verification): see docs/skill-setup.md.

Prerequisites

• Auth must be set up first (/iblai-vibe-auth)
• MCP server + skills configured (@iblai/mcp in .mcp.json)
• AgentSettingsProvider must wrap the route (see /iblai-vibe-agent-setting Step 2 if not already set up)
• Ask the user for a real mentorId (agent UUID). Do NOT invent one.
• The spend-cap endpoints are RBAC-gated admin endpoints — a user without access sees a friendly "no access" panel per sub-tab (403).

Step 1: Check Environment

Before proceeding, check for an iblai.env in the project root. Look for PLATFORM, DOMAIN, and TOKEN variables. If the file does not exist or is missing these variables, tell the user: "You need an iblai.env with your platform configuration. Download the template and fill in your values: curl -o iblai.env https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/iblai.env"

Step 2: Mount AgentSpendCapsTab

// app/(app)/agents/[mentorId]/billing/page.tsx
"use client";

import { AgentSpendCapsTab } from "@iblai/iblai-js/web-containers/next";

export default function AgentBillingPage() {
  return (
    <div className="flex h-full flex-col bg-white">
      <AgentSpendCapsTab />
    </div>
  );
}

AgentSpendCapsTab reads tenantKey and mentorId from AgentSettingsProvider. No props are required for the standard mount.

Step 3: Customize Labels (Optional)

import { AgentSpendCapsTab } from "@iblai/iblai-js/web-containers/next";

<AgentSpendCapsTab
  labels={{
    header: { title: "Spend limits" },
    subTabs: { agent: "Agent limit", users: "User limits" },
  }}
/>;

Step 4: Use MCP Tools for Customization

get_component_info("AgentSpendCapsTab")
get_component_info("SpendCapUsage")
get_component_info("AgentSettingsProvider")

<AgentSpendCapsTab> Props

Import from @iblai/iblai-js/web-containers/next.

What the tab renders

• Header — "Billing" title and "Set spend limits for this agent and its users, and see how much has been used."
• This Agent / Per User sub-tabs — the two agent-level scopes. The tab ratchets its height so switching sub-tabs never shrinks the dialog it is hosted in.
• No-access state — when the current user lacks permission for a scope's endpoints (403), that sub-tab's content is replaced by a "no access" notice.

Shared spend-cap editor (both scopes)

Both sub-tabs edit a cap through the same SpendCapForm:

• Enable toggle — "Put a ceiling on AI spend…" capability gate. While on, everything the limit covers counts toward the amount; fields collapse when toggled off. The flag rides along on save.
• Usage strip (saved caps only) — "Daily/Weekly/Monthly/Yearly Usage" with a progress bar (blue, amber at ≥80%, red when exceeded) and Spent / % of limit used / Remaining figures, plus Disabled / Alert only / Exceeded badges as applicable.
• Spend Limit (USD) — positive decimal; sent as a 2-decimal string.
• Resets Every — Day / Week / Month / Year.
• When the Limit Is Reached — Block Requests (new chat and training requests are refused until the period resets) or Alert Only (requests continue; admins are alerted).
• Alert At (% of Limit) — comma-separated percentages (default 80, 95) at which admins get a near-limit alert.
• Delete Limit (saved caps only) — confirmation dialog before removal. Save creates the cap on first save and updates it after (the PUT is an upsert).
• Until a cap exists the form shows "No spend limit configured yet — set an amount and save to create one."

This Agent sub-tab

The agent's own singleton spend cap — everything spent on this agent by anyone counts toward it.

Per User sub-tab

Explicit (user, agent) limits — "Limit what specific users can spend on this agent."

• Table — User (email-first, linked to the same profile viewer as the Management tab; clicking the row opens it too), Limit ($2.00 / Week), Status (direct enable toggle that saves immediately, plus Exceeded / Alert-only badges), and a per-row actions menu (Edit / Delete).
• Add User Limit — opens the New User Limit modal: pick the user through a debounced platform-user search (min 2 characters, email-only options — no free-text usernames), then fill the same spend-cap form. Edit mode skips the picker and goes straight to the form for the cap's user.
• Delete — confirmation dialog showing the user's email.

Related Exports

From @iblai/iblai-js/web-containers/next:

• AGENT_SPEND_CAPS_TAB_LABELS -- the default label bundle.
• SpendCapsTabLabels -- type for the full label bundle.
• AgentSpendCapsTabProps -- props type for the tab.
• SPEND_CAPS_SUB_TABS -- the sub-tab keys (agent, users).
• useSpendCaps -- the tab's data hook (caps + save/delete per scope), for custom UI on the same endpoints.
• SpendCapUsage, SpendCapUsageProps -- learner-safe usage indicator for chat surfaces: renders progress zones and percentages only (never dollar amounts), a warning banner near a limit, and a blocked banner once a hard-block cap is exceeded. Renders nothing while everything is in the "ok" zone unless showWhenOk is set.

From @iblai/iblai-js/data-layer -- the RTK Query hooks and types the tab uses, for custom UI built on the same endpoints:

• Agent cap: useGetAgentSpendCapQuery, useUpsertAgentSpendCapMutation, useDeleteAgentSpendCapMutation
• Per-user caps: useListAgentUserSpendCapsQuery, useGetUserSpendCapQuery, useUpsertUserSpendCapMutation, useDeleteUserSpendCapMutation
• Organization cap (workspace-wide singleton): useGetTenantSpendCapQuery, useUpsertTenantSpendCapMutation, useDeleteTenantSpendCapMutation
• Organization-wide agent-cap list: useListAgentSpendCapsQuery (optional mentor filter)
• User-safe status: useGetSpendCapStatusQuery
• Types: SpendCap, SpendCapUpsertRequest, SpendCapIntervalType, SpendCapEnforcement, SpendCapScope, SpendCapStatusSummary, SpendCapStatusItem, SpendCapStatusZone, SpendCapExceededErrorBody
• SPEND_CAP_EXCEEDED_ERROR_CODE -- the spend_cap_exceeded error code carried by blocked requests (HTTP 429 body / WebSocket frame), distinguishing a spend-cap block from a genuine provider rate limit.

Step 5: Verify

Run /iblai-vibe-ops-test before telling the user the work is ready:

1. pnpm build -- must pass with zero errors
2. pnpm test -- vitest must pass
3. Touch test /agents/<id>/billing in the browser as /iblai-vibe-ops-test says: open it, use every control this skill added, read the console, check the phone width.

Important Notes

• Redux store: Must include mentorReducer and mentorMiddleware
• initializeDataLayer(): 5 args (v1.2+)
• @reduxjs/toolkit: Deduplicated via webpack aliases in next.config.ts
• Peer deps: sonner and @iblai/iblai-web-mentor must be installed (pnpm add sonner @iblai/iblai-web-mentor)
• Shared provider: AgentSettingsProvider must wrap the route at a layout level. See /iblai-vibe-agent-setting Step 2 for the full snippet.
• First-run 404 is normal: the singleton GETs 404 until a cap is first saved — that is the documented "no cap configured" state, not an error. The first Save creates the row.
• Counters are read-only: current_spend_usd, remaining_usd, and is_exceeded are reconciled server-side and only rendered — never submitted. Admins write interval_type, max_cost_usd (decimal string), enforcement, alert_thresholds, enabled.
• PUT is an upsert: the status toggles in the tables save immediately by re-submitting the cap's current fields with the flipped enabled flag.
• Username key, email display: per-user caps are keyed by username in the API; the UI deliberately shows the email everywhere. The user is picked via search — no free-text usernames. A cap read echoes username, email and user_full_name, so the table renders the person without a second request.
• Enforcement is server-side: with block, an exceeded cap makes chat/training requests fail with HTTP 429 (or a WebSocket error frame) whose body carries error_code: "spend_cap_exceeded". Handle it in custom chat UI, or mount SpendCapUsage to warn users before they hit it.
• Three scopes: organization (workspace-wide), agent, and per-user-per- agent — the tightest applicable cap governs. This tab manages the two agent-level scopes; the workspace-wide limit belongs to the organization settings Billing surface (/iblai-vibe-billing, which also lists every agent's cap in one place).
• RBAC: each scope's endpoints are gated separately; a 403 renders the denied panel for that sub-tab only.
• Brand guidelines: BRAND.md

Spend Caps REST API

For custom UI beyond the tab. All endpoints are prefixed with ${dmUrl}/api/ai-mentor/orgs/{org}/ where dmUrl is NEXT_PUBLIC_API_BASE_URL. Auth: Authorization: Token <token>. Use the canonical agents/ spelling — mentors/ is a deprecated alias.

Agent spend cap (singleton per agent)

Upsert body:

{
  "interval_type": "day",
  "max_cost_usd": "10.00",
  "enforcement": "block",
  "alert_thresholds": [80, 95],
  "enabled": true
}

interval_type: day | week | month | year. enforcement: block | alert_only. max_cost_usd is a decimal string. Responses add the read-only counters (current_spend_usd, remaining_usd, is_exceeded, period_started_at, last_reconciled_at).

Per-user limits on an agent

The list may come back as a bare array or a DRF limit/offset envelope depending on deployment — the SDK slice normalizes both.

Organization scope + organization-wide listing

User-safe status

Enforcement error

A hard-block cap that is exceeded makes chat/training requests fail with HTTP 429 (or a WebSocket error frame):

{
  "error_code": "spend_cap_exceeded",
  "error": "...",
  "message": "...",
  "details": { "scope": "agent", "interval_type": "day", "mentor_unique_id": "..." }
}

Match on error_code === "spend_cap_exceeded" (SPEND_CAP_EXCEEDED_ERROR_CODE) — a genuine provider rate limit also uses status 429.