feat(metering): emit tool_calls usage event from proxy execute [PLEN-2509]

@shamsharoonchecks n/achecks…feat/meter-proxy-execute-PLEN-2509 → master8 files · +214 −4review: @rohanprabhureview: @sohamganatrareview: @sarthakreview: @acsrujanreview: @kaavee315review: @lingalarahul7review: @anshugarg15updated 2w ago

GitHub

▸Description · 7 noise

Description

Closes the proxy-execute metering loophole. Proxy execute (/api/v3/tools/execute/proxy + tool-router session proxy_execute paths) doesn't currently emit metering events, so customers on STARTER/GROWTH plans can route heavy traffic through proxy to bypass tool_calls billing.

Linear: PLEN-2509

Discovered during the billing v0 staging dry-run on May 18-19 — proxy was the only major execute surface not metered.

What changed

proxy_execution_logger.ts — emits TOOL_CALL_USAGE_EVENT_TYPE on upstream-success only, alongside the existing tool-execution log write. Mirrors the emit shape from execute_tool.ts:1107-1136 so the downstream events/handlers/usage_metered/handler.ts treats it identically.
ProxyLogContext gains orgNanoId. Both callers (proxy.ts direct route + proxyExecuteForSessionRPC.ts) pass project.orgId.
Identity fallback matches execute_tool.ts:1104-1105 — when neither entityId nor a resolved connected_account is present, falls back to external_user_id: 'default' so the metering schema's "user_id required unless connected_account_id" rule is satisfied for the custom_connection_data path.

Why this approach

Single emit site at logProxyExecution covers all three proxy entry points (direct API route + session proxy_execute + internal proxy_execute) because they all funnel through proxyExecuteForSessionRPC → executeProxy → logProxyExecution. The existing logger already has logId, the resolved toolkitSlug from auth meta, buildActionName() (returns <TOOLKIT>_PROXY_EXECUTE), and the right gating for internal probes. Reusing it keeps DB-log writing and metering-event emission consistent.

Premium classification

Falls out automatically. The handler reads normalized_toolkit_slug (e.g. gmail, exa, gemini) and runs classifyPremiumToolkit, so a proxy call to a premium toolkit emits a second premium_tool_calls event with the correct category dimension. No additional code here.

How did I test this PR

Unit tests added in proxy_execution_logger.test.ts cover success/error/4xx/session_id/'default' fallback paths.
Oxlint clean on touched files.
Will validate end-to-end in staging post-merge: fire a proxy call against a connected toolkit on a post-cutoff org with LD on → expect Tool Calls (and Premium Tool Calls for premium toolkits) to increment in Metronome.

▸ 7 bot/status comments hidden

@linear-code[bot]3w ago

Context

POST /api/v3/tools/execute/proxy (handler at apps/apollo/src/pages/api/v3/tools/execute/proxy.ts, lib at apps/apollo/src/lib/connected_accounts/executeProxy/) is currently not metered. No emitEvent / trackMeteredUsage calls in either path.

Meanwhile typed tool execution at execute_tool.ts:1107 emits TOOL_CALL_USAGE_EVENT_TYPE after every successful tool call. This creates an incentive for customers on STARTER/GROWTH plans to shift heavy traffic to proxy execute to bypass billing.

Discovered during billing v0 staging dry-run (May 18-19, 2026).

Goal

Emit a tool_calls metering event on every successful proxy execution, attributing usage to the org / project / connected account / toolkit. Premium classification (premium_tool_calls fanout in events/handlers/usage_metered/handler.ts) will happen automatically once normalized_toolkit_slug is populated — so e.g. Exa or Tavily proxy calls will correctly bill at premium rates.

Implementation sketch

In executeProxy/index.ts (or the API route handler after executeProxy returns Ok), emit a TOOL_CALL_USAGE_EVENT_TYPE event mirroring the shape at execute_tool.ts:1107-1132
Decide a tool_slug convention. Two options:
- <TOOLKIT>_PROXY_EXECUTE (e.g. GITHUB_PROXY_EXECUTE) — preserves toolkit context in the slug
- PROXY_EXECUTE — simpler, toolkit info still on the toolkit_slug dimension
Source toolkit_slug from the connected account auth config — already in scope inside executeProxy
Verify the tool_log row gets written so log_id is available (or add a tool_log insert if not)
Tests asserting the event fires with correct dimensions for both authed and no-auth proxy paths

loading diff…

Description

Discovered during the billing v0 staging dry-run on May 18-19 — proxy was the only major execute surface not metered.

What changed

proxy_execution_logger.ts — emits TOOL_CALL_USAGE_EVENT_TYPE on upstream-success only, alongside the existing tool-execution log write. Mirrors the emit shape from execute_tool.ts:1107-1136 so the downstream events/handlers/usage_metered/handler.ts treats it identically.

ProxyLogContext gains orgNanoId. Both callers (proxy.ts direct route + proxyExecuteForSessionRPC.ts) pass project.orgId.

Identity fallback matches execute_tool.ts:1104-1105 — when neither entityId nor a resolved connected_account is present, falls back to external_user_id: 'default' so the metering schema's "user_id required unless connected_account_id" rule is satisfied for the custom_connection_data path.

Why this approach

How did I test this PR

Unit tests added in proxy_execution_logger.test.ts cover success/error/4xx/session_id/'default' fallback paths.

Oxlint clean on touched files.

Will validate end-to-end in staging post-merge: fire a proxy call against a connected toolkit on a post-cutoff org with LD on → expect Tool Calls (and Premium Tool Calls for premium toolkits) to increment in Metronome.

Context

Discovered during billing v0 staging dry-run (May 18-19, 2026).

Goal

Implementation sketch

In executeProxy/index.ts (or the API route handler after executeProxy returns Ok), emit a TOOL_CALL_USAGE_EVENT_TYPE event mirroring the shape at execute_tool.ts:1107-1132

Decide a tool_slug convention. Two options:

<TOOLKIT>_PROXY_EXECUTE (e.g. GITHUB_PROXY_EXECUTE) — preserves toolkit context in the slug
PROXY_EXECUTE — simpler, toolkit info still on the toolkit_slug dimension

Source toolkit_slug from the connected account auth config — already in scope inside executeProxy

Verify the tool_log row gets written so log_id is available (or add a tool_log insert if not)

Tests asserting the event fires with correct dimensions for both authed and no-auth proxy paths

Contributor	Contribution	Files
Zen Agent	53%	4
Himanshu Dixit	15%	2
devin-ai-integration[bot]	14%	3
shams haroon	11%	6
anshugarg15	3%	3

Flag	Coverage Δ
e2e-tests	`6.04% <2.04%> (-0.01%)`	:arrow_down:
self-hosted-tests	`5.58% <0.00%> (-0.01%)`	:arrow_down:
thermos-unit-tests	`?`
unit-tests	`58.95% <89.79%> (+0.01%)`	:arrow_up:

Files with missing lines	Coverage Δ
apps/apollo/src/lib/events/types/shared.ts	`100.00% <100.00%> (ø)`
...V2/features/execution/proxyExecuteForSessionRPC.ts	`74.08% <100.00%> (+0.05%)`	:arrow_up:
...pps/apollo/src/pages/api/v3/tools/execute/proxy.ts	`98.83% <100.00%> (+<0.01%)`	:arrow_up:
...ed_accounts/executeProxy/proxy_execution_logger.ts	`88.30% <89.13%> (+0.30%)`	:arrow_up:

feat(metering): emit tool_calls usage event from proxy execute [PLEN-2509]

Description

What changed

Why this approach

Premium classification

How did I test this PR

Context

Goal

Implementation sketch

Description

What changed

Why this approach

Premium classification

How did I test this PR

Context

Goal

Implementation sketch

Estimate

Out of scope

🔍 Suggested Reviewers

💡 Recommendation

🧪 Test Results Summary (Self-Hosted Tests)

🧪 Test Results Summary (Unit Tests)

Codecov Report

🧪 Test Results Summary (E2E Tests)