feat(client): Agent Control settings page for the billing exception agent

[emoss08]

Description

Adds the client-side surface for the billing exception agent's per-organization control. The backend AgentControl entity, GraphQL API, and the @trenova/graphql operations already landed on master, but there was no UI to actually read or change these settings — this PR builds that page so an operator can enable the agent, toggle shadow mode, and set the decision timeout without hand-writing GraphQL.

It mirrors the existing cost-control / dash-control settings pattern end to end (suspense query → react-hook-form + zod → useApiMutation → FormSaveDock). The form surfaces a warning callout when shadow mode is on, since that's the state where runs execute but proposals are intentionally never surfaced.

Related Issue or Discussion

Follow-up to the merged billing-exception-agent work (#517). Requested directly by the maintainer.

Type of Change

• Feature

Scope

• client/apps/web/src/routes/agent-control/ — admin settings page + form (shadow mode, enablement, decision timeout; shadow-mode warning callout)
• client/apps/web/src/lib/graphql/agent-control.ts — fetch/update wrappers over the AgentControlSettings query and UpdateAgentControl mutation (fragment unmasked via getFragmentData)
• client/apps/web/src/types/agent-control.ts — zod form schema (timeout bounded 5 min–7 days)
• client/apps/web/src/router.tsx — /admin/agent-control route, gated on agent_control:read
• client/apps/web/src/config/navigation.config.ts — "Agent Control" entry under the Organization group
• client/packages/shared/src/types/permission.ts — adds the agent_run / agent_proposal / agent_exception / agent_control resources to the client permission map

Validation

• cd client && pnpm --filter @trenova/web typecheck — passes
• cd client && pnpm --filter @trenova/web lint — no errors/warnings in the new files (pre-existing better-tailwindcss warnings elsewhere are unrelated)
• cd client && pnpm build — not run in this environment; typecheck covers the type surface
• cd services/tms checks — n/a, this PR is client-only (no Go changes)

Screenshots or Recordings

Not captured — no running app/browser was available in this environment. The page reuses the shared settings-form primitives (Card, SwitchField, NumberField, FormSaveDock), so it renders consistently with the existing Cost/Dash/Settlement Control pages.

Deployment Notes

• Client-only; no migrations or backend changes.
• The new nav item and route are permission-gated on agent_control:read; users need that grant to see the page and agent_control:update to save.
• Depends on the already-merged AgentControl GraphQL API; no new API surface introduced here.

Checklist

• I kept the change focused and reviewable.
• I followed AGENTS.md, CLAUDE.md, and existing repository patterns.
• I added or updated tests for behavior changes, or explained why tests are not applicable — no client unit tests were added; this is a settings form built entirely from already-tested shared primitives and generated GraphQL documents, matching the sibling control pages which are likewise untested at the unit level.
• I updated relevant documentation, examples, migrations, or configuration.
• I did not include secrets, credentials, private customer data, unrelated refactors, or placeholder code.

🤖 Generated with Claude Code

---

Generated by Claude Code

Summary by CodeRabbit

• New Features
  • Added an Agent Control section to the admin sidebar.
  • Admins can configure the billing exception agent, including enablement, shadow mode, and decision timeout.
  • Added validation to ensure timeout values are whole numbers between 5 minutes and 7 days.
  • Changes can be saved with confirmation feedback and updated settings displayed immediately.
  • Access is restricted to administrators with the required permission.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	trenova	6f66df4	Jul 24 2026, 04:55 PM

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5bc1280e-bce0-4ea7-af8c-cede39cc5d0b

📥 Commits

Reviewing files that changed from the base of the PR and between 33f56f5 and 6f66df4.

📒 Files selected for processing (7)

• client/apps/web/src/config/navigation.config.ts
• client/apps/web/src/lib/graphql/agent-control.ts
• client/apps/web/src/router.tsx
• client/apps/web/src/routes/agent-control/_components/agent-control-form.tsx
• client/apps/web/src/routes/agent-control/page.tsx
• client/apps/web/src/types/agent-control.ts
• client/packages/shared/src/types/permission.ts

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

📝 Walkthrough

Walkthrough

Adds a protected Agent Control admin page with navigation, typed GraphQL read/update operations, validated billing-agent settings, conditional warnings, and query refresh behavior.

Changes

Agent Control configuration

Layer / File(s)	Summary
Agent Control contracts and data access client/packages/shared/src/types/permission.ts, client/apps/web/src/types/agent-control.ts, client/apps/web/src/lib/graphql/agent-control.ts	Adds Agent Control permission resources, validation for billing-agent settings, and typed GraphQL query and mutation helpers.
Agent Control form behavior client/apps/web/src/routes/agent-control/_components/agent-control-form.tsx	Loads settings into a form, submits updates, invalidates the agent-control query, and displays a warning when billing-agent shadow mode is enabled.
Admin route and navigation wiring client/apps/web/src/routes/agent-control/page.tsx, client/apps/web/src/router.tsx, client/apps/web/src/config/navigation.config.ts	Adds the lazily loaded protected route, page layout, and Organization navigation entry.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Admin
  participant AgentControlPage
  participant AgentControlForm
  participant GraphQLAPI
  Admin->>AgentControlPage: open /admin/agent-control
  AgentControlPage->>AgentControlForm: render
  AgentControlForm->>GraphQLAPI: fetchAgentControl()
  GraphQLAPI-->>AgentControlForm: current settings
  Admin->>AgentControlForm: submit validated settings
  AgentControlForm->>GraphQLAPI: updateAgentControl(input)
  GraphQLAPI-->>AgentControlForm: updated settings
  AgentControlForm-->>Admin: show success toast

Loading

Suggested reviewers: claude

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/billing-exception-agent-phase-1-l4uyab

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}