feat(copilot): answer account billing questions from a live snapshot

Adds the no-argument get_account_billing tool: the handler combines the
org-aware billing lookups (usage data, credit balance, usage-limit info)
into one snapshot — plan, current-period usage vs limit with remaining,
and purchased credit balance — always scoped to the requesting user.
Catalog and schema mirrors regenerated from the mothership definitions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: j15z

apps/sim/lib/copilot/generated/tool-catalog-v1.ts

@@ -56,6 +56,7 @@ export interface ToolCatalogEntry {
     | 'generate_audio'
     | 'generate_image'
     | 'generate_video'
+    | 'get_account_billing'
     | 'get_block_outputs'
     | 'get_block_upstream_references'
     | 'get_deployed_workflow_state'
@@ -172,6 +173,7 @@ export interface ToolCatalogEntry {
     | 'generate_audio'
     | 'generate_image'
     | 'generate_video'
+    | 'get_account_billing'
     | 'get_block_outputs'
     | 'get_block_upstream_references'
     | 'get_deployed_workflow_state'
@@ -2901,6 +2903,14 @@ export const GenerateVideo: ToolCatalogEntry = {
   capabilities: ['file_input', 'file_output', 'generated_media'],
 }
 
+export const GetAccountBilling: ToolCatalogEntry = {
+  id: 'get_account_billing',
+  name: 'get_account_billing',
+  route: 'sim',
+  mode: 'async',
+  parameters: { type: 'object', properties: {} },
+}
+
 export const GetBlockOutputs: ToolCatalogEntry = {
   id: 'get_block_outputs',
   name: 'get_block_outputs',
@@ -5931,6 +5941,7 @@ export const TOOL_CATALOG: Record<string, ToolCatalogEntry> = {
   [GenerateAudio.id]: GenerateAudio,
   [GenerateImage.id]: GenerateImage,
   [GenerateVideo.id]: GenerateVideo,
+  [GetAccountBilling.id]: GetAccountBilling,
   [GetBlockOutputs.id]: GetBlockOutputs,
   [GetBlockUpstreamReferences.id]: GetBlockUpstreamReferences,
   [GetDeployedWorkflowState.id]: GetDeployedWorkflowState,

apps/sim/lib/copilot/generated/tool-schemas-v1.ts

@@ -2809,6 +2809,13 @@ export const TOOL_RUNTIME_SCHEMAS: Record<string, ToolRuntimeSchemaEntry> = {
     },
     resultSchema: undefined,
   },
+  get_account_billing: {
+    parameters: {
+      type: 'object',
+      properties: {},
+    },
+    resultSchema: undefined,
+  },
   get_block_outputs: {
     parameters: {
       type: 'object',

apps/sim/lib/copilot/tool-executor/register-handlers.ts

@@ -12,6 +12,7 @@ import {
   DiffWorkflows,
   FunctionExecute,
   GenerateApiKey,
+  GetAccountBilling,
   GetBlockOutputs,
   GetBlockUpstreamReferences,
   GetDeployedWorkflowState,
@@ -52,6 +53,7 @@ import {
 } from '@/lib/copilot/generated/tool-catalog-v1'
 import { createServerToolHandler } from '@/lib/copilot/tools/registry/server-tool-adapter'
 import { getRegisteredServerToolNames } from '@/lib/copilot/tools/server/router'
+import { executeGetAccountBilling } from '../tools/handlers/account'
 import { executeDeployCustomBlock } from '../tools/handlers/deployment/custom-block'
 import {
   executeDeployApi,
@@ -134,6 +136,7 @@ function h(fn: (params: any, context: any) => Promise<any>): ToolHandler {
 function buildHandlerMap(): Record<string, ToolHandler> {
   return {
     [ListUserWorkspaces.id]: h((_p, c) => executeListUserWorkspaces(c)),
+    [GetAccountBilling.id]: h((_p, c) => executeGetAccountBilling(c)),
     [GetWorkflowData.id]: h(executeGetWorkflowData),
     [GetWorkflowRunOptions.id]: h(executeGetWorkflowRunOptions),
     [GetBlockOutputs.id]: h(executeGetBlockOutputs),

apps/sim/lib/copilot/tools/handlers/account.test.ts

@@ -0,0 +1,121 @@
+/**
+ * @vitest-environment node
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockGetUserUsageData, mockGetCreditBalance, mockGetUserUsageLimitInfo } = vi.hoisted(
+  () => ({
+    mockGetUserUsageData: vi.fn(),
+    mockGetCreditBalance: vi.fn(),
+    mockGetUserUsageLimitInfo: vi.fn(),
+  })
+)
+
+vi.mock('@/lib/billing', () => ({
+  getUserUsageData: mockGetUserUsageData,
+  getCreditBalance: mockGetCreditBalance,
+  getUserUsageLimitInfo: mockGetUserUsageLimitInfo,
+}))
+
+import type { ExecutionContext } from '@/lib/copilot/request/types'
+import { executeGetAccountBilling } from '@/lib/copilot/tools/handlers/account'
+
+const context = { userId: 'user-1' } as ExecutionContext
+
+describe('executeGetAccountBilling', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns the org-aware plan, usage, and credit snapshot', async () => {
+    const periodEnd = new Date('2026-09-01T00:00:00Z')
+    mockGetUserUsageData.mockResolvedValue({
+      currentUsage: 18.5,
+      limit: 40,
+      percentUsed: 46.25,
+      isWarning: false,
+      isExceeded: false,
+      billingPeriodStart: new Date('2026-08-01T00:00:00Z'),
+      billingPeriodEnd: periodEnd,
+      lastPeriodCost: 31,
+    })
+    mockGetCreditBalance.mockResolvedValue({
+      balance: 25,
+      entityType: 'organization',
+      entityId: 'org-1',
+    })
+    mockGetUserUsageLimitInfo.mockResolvedValue({
+      currentLimit: 40,
+      canEdit: false,
+      minimumLimit: 0,
+      plan: 'team',
+      updatedAt: null,
+      scope: 'organization',
+      organizationId: 'org-1',
+    })
+
+    const result = await executeGetAccountBilling(context)
+
+    expect(mockGetUserUsageData).toHaveBeenCalledWith('user-1')
+    expect(mockGetCreditBalance).toHaveBeenCalledWith('user-1')
+    expect(mockGetUserUsageLimitInfo).toHaveBeenCalledWith('user-1')
+    expect(result).toEqual({
+      success: true,
+      output: {
+        plan: 'team',
+        billingScope: 'organization',
+        organizationId: 'org-1',
+        usage: {
+          currentPeriodCost: 18.5,
+          limit: 40,
+          remaining: 21.5,
+          percentUsed: 46.25,
+          isExceeded: false,
+          billingPeriodEnd: periodEnd,
+        },
+        credits: { balance: 25, scope: 'organization' },
+      },
+    })
+  })
+
+  it('clamps remaining to zero when usage exceeds the limit', async () => {
+    mockGetUserUsageData.mockResolvedValue({
+      currentUsage: 45,
+      limit: 40,
+      percentUsed: 112.5,
+      isWarning: false,
+      isExceeded: true,
+      billingPeriodStart: null,
+      billingPeriodEnd: null,
+      lastPeriodCost: 0,
+    })
+    mockGetCreditBalance.mockResolvedValue({ balance: 0, entityType: 'user', entityId: 'user-1' })
+    mockGetUserUsageLimitInfo.mockResolvedValue({
+      currentLimit: 40,
+      canEdit: true,
+      minimumLimit: 0,
+      plan: 'pro',
+      updatedAt: null,
+      scope: 'user',
+      organizationId: null,
+    })
+
+    const result = await executeGetAccountBilling(context)
+
+    expect(result.success).toBe(true)
+    expect(result.output).toMatchObject({
+      plan: 'pro',
+      usage: { remaining: 0, isExceeded: true },
+    })
+  })
+
+  it('surfaces a billing lookup failure as a tool error', async () => {
+    mockGetUserUsageData.mockRejectedValue(new Error('stats row missing'))
+    mockGetCreditBalance.mockResolvedValue({ balance: 0, entityType: 'user', entityId: 'user-1' })
+    mockGetUserUsageLimitInfo.mockResolvedValue({})
+
+    const result = await executeGetAccountBilling(context)
+
+    expect(result).toEqual({ success: false, error: 'stats row missing' })
+  })
+})

apps/sim/lib/copilot/tools/handlers/account.ts

@@ -0,0 +1,43 @@
+import { toError } from '@sim/utils/errors'
+import { getCreditBalance, getUserUsageData, getUserUsageLimitInfo } from '@/lib/billing'
+import type { ExecutionContext, ToolCallResult } from '@/lib/copilot/request/types'
+
+/**
+ * Live billing snapshot for the requesting user: plan, current-period usage
+ * against its limit, and purchased credit balance. All three sources are
+ * org-aware — a member whose subscription lives on an organization gets the
+ * org's plan, limit, and credit pool, with `billingScope`/`organizationId`
+ * saying which applied.
+ */
+export async function executeGetAccountBilling(context: ExecutionContext): Promise<ToolCallResult> {
+  try {
+    const [usage, credits, limitInfo] = await Promise.all([
+      getUserUsageData(context.userId),
+      getCreditBalance(context.userId),
+      getUserUsageLimitInfo(context.userId),
+    ])
+
+    return {
+      success: true,
+      output: {
+        plan: limitInfo.plan,
+        billingScope: limitInfo.scope,
+        organizationId: limitInfo.organizationId,
+        usage: {
+          currentPeriodCost: usage.currentUsage,
+          limit: usage.limit,
+          remaining: Math.max(0, usage.limit - usage.currentUsage),
+          percentUsed: usage.percentUsed,
+          isExceeded: usage.isExceeded,
+          billingPeriodEnd: usage.billingPeriodEnd,
+        },
+        credits: {
+          balance: credits.balance,
+          scope: credits.entityType,
+        },
+      },
+    }
+  } catch (error) {
+    return { success: false, error: toError(error).message }
+  }
+}

apps/sim/lib/copilot/tools/tool-display.ts

@@ -469,6 +469,7 @@ const TOOL_TITLES: Record<string, string> = {
   function_execute: 'Running code',
   complete_scheduled_task: 'Completing scheduled task',
   generate_api_key: 'Generating API key',
+  get_account_billing: 'Checking plan and usage',
   get_block_outputs: 'Getting block outputs',
   get_block_upstream_references: 'Getting block references',
   get_deployed_workflow_state: 'Getting deployed workflow',