Merge pull request #518 from emoss08/claude/billing-exception-agent-phase-1-l4uyab

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

Author: emoss08

client/apps/web/src/config/navigation.config.ts

@@ -962,6 +962,13 @@ export const adminLinks: SidebarLink[] = [
     resource: Resource.DashControl,
     requiredOperation: Operation.Read,
   },
+  {
+    href: "/admin/agent-control",
+    title: "Agent Control",
+    group: "Organization",
+    resource: Resource.AgentControl,
+    requiredOperation: Operation.Read,
+  },
   {
     href: "/admin/cost-control",
     title: "Cost Control",

client/apps/web/src/lib/graphql/agent-control.ts

@@ -0,0 +1,30 @@
+import {
+  AgentControlFieldsFragmentDoc,
+  AgentControlSettingsDocument,
+  UpdateAgentControlDocument,
+  type AgentControlFieldsFragment,
+  type AgentControlInput,
+} from "@trenova/graphql/generated/graphql";
+import { getFragmentData } from "@trenova/graphql/generated";
+import { requestGraphQL } from "@trenova/shared/lib/graphql";
+
+export type AgentControl = AgentControlFieldsFragment;
+
+export async function fetchAgentControl(): Promise<AgentControl> {
+  const data = await requestGraphQL({
+    document: AgentControlSettingsDocument,
+    operationName: "AgentControlSettings",
+  });
+
+  return getFragmentData(AgentControlFieldsFragmentDoc, data.agentControl);
+}
+
+export async function updateAgentControl(input: AgentControlInput): Promise<AgentControl> {
+  const data = await requestGraphQL({
+    document: UpdateAgentControlDocument,
+    operationName: "UpdateAgentControl",
+    variables: { input },
+  });
+
+  return getFragmentData(AgentControlFieldsFragmentDoc, data.updateAgentControl);
+}

client/apps/web/src/router.tsx

@@ -883,6 +883,14 @@ const routes: RouteObject[] = [
                   return { Component: DashControlPage };
                 },
               },
+              {
+                path: "agent-control",
+                loader: createPermissionLoader(Resource.AgentControl, Operation.Read),
+                async lazy() {
+                  const { AgentControlPage } = await import("@/routes/agent-control/page");
+                  return { Component: AgentControlPage };
+                },
+              },
               {
                 path: "distance-controls",
                 loader: createPermissionLoader(Resource.DistanceControl),

client/apps/web/src/routes/agent-control/_components/agent-control-form.tsx

@@ -0,0 +1,124 @@
+import { NumberField } from "@/components/fields/number-field";
+import { SwitchField } from "@/components/fields/switch-field";
+import { FormSaveDock } from "@/components/form-save-dock";
+import { useApiMutation } from "@/hooks/use-api-mutation";
+import { fetchAgentControl, updateAgentControl } from "@/lib/graphql/agent-control";
+import { agentControlSchema, type AgentControlFormValues } from "@/types/agent-control";
+import { Alert, AlertDescription, AlertTitle } from "@trenova/shared/components/ui/alert";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@trenova/shared/components/ui/card";
+import { Form, FormControl, FormGroup } from "@trenova/shared/components/ui/form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useQueryClient, useSuspenseQuery } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { FormProvider, type Resolver, useForm, useFormContext, useWatch } from "react-hook-form";
+import { toast } from "sonner";
+
+const AGENT_CONTROL_QUERY_KEY = ["agent-control"];
+
+export default function AgentControlForm() {
+  const queryClient = useQueryClient();
+  const { data } = useSuspenseQuery({
+    queryKey: AGENT_CONTROL_QUERY_KEY,
+    queryFn: fetchAgentControl,
+  });
+
+  const defaultValues: AgentControlFormValues = {
+    billingAgentEnabled: data.billingAgentEnabled,
+    shadowMode: data.shadowMode,
+    decisionTimeoutSeconds: data.decisionTimeoutSeconds,
+  };
+
+  const form = useForm<AgentControlFormValues>({
+    resolver: zodResolver(agentControlSchema) as Resolver<AgentControlFormValues>,
+    defaultValues,
+    values: defaultValues,
+  });
+  const { handleSubmit, setError, reset } = form;
+
+  const mutation = useApiMutation({
+    mutationFn: (values: AgentControlFormValues) => updateAgentControl(values),
+    onSuccess: (_, values) => {
+      toast.success("Agent control updated");
+      reset(values);
+      void queryClient.invalidateQueries({ queryKey: AGENT_CONTROL_QUERY_KEY });
+    },
+    setFormError: setError,
+    resourceName: "Agent Control",
+  });
+
+  const onSubmit = useCallback(
+    (values: AgentControlFormValues) => mutation.mutate(values),
+    [mutation],
+  );
+
+  return (
+    <FormProvider {...form}>
+      <Form onSubmit={handleSubmit(onSubmit)}>
+        <div className="flex flex-col gap-4 pb-14">
+          <BillingAgentCard />
+          <FormSaveDock saveButtonContent="Save Changes" />
+        </div>
+      </Form>
+    </FormProvider>
+  );
+}
+
+function BillingAgentCard() {
+  const { control } = useFormContext<AgentControlFormValues>();
+  const shadowMode = useWatch({ control, name: "shadowMode" });
+  const billingAgentEnabled = useWatch({ control, name: "billingAgentEnabled" });
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Billing Exception Agent</CardTitle>
+        <CardDescription>
+          The billing exception agent inspects blocked billing queue items, diagnoses why they are
+          held, and proposes resolutions for a human to approve. It never approves or transitions an
+          item itself.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="max-w-prose">
+        <FormGroup cols={1}>
+          <FormControl>
+            <SwitchField
+              control={control}
+              name="billingAgentEnabled"
+              label="Enable Billing Exception Agent"
+              description="Allow the agent to run against this organization's blocked billing queue items."
+              position="left"
+            />
+          </FormControl>
+          <FormControl>
+            <SwitchField
+              control={control}
+              name="shadowMode"
+              label="Shadow Mode"
+              description="While on, the agent runs and stores its proposals for observation but they are never surfaced or actionable. Turn off only once you trust the agent's suggestions."
+              position="left"
+            />
+          </FormControl>
+          {shadowMode && billingAgentEnabled ? (
+            <Alert variant="warning">
+              <AlertTitle>Proposals are hidden</AlertTitle>
+              <AlertDescription>
+                Shadow mode is on, so runs complete and persist proposals but nothing appears for
+                review and no decisions are awaited. Turn shadow mode off to surface proposals and
+                enable human decisions.
+              </AlertDescription>
+            </Alert>
+          ) : null}
+          <FormControl className="max-w-[420px]">
+            <NumberField
+              control={control}
+              name="decisionTimeoutSeconds"
+              label="Decision Timeout (seconds)"
+              description="How long a proposal waits for a human decision before its proposals expire and the run is parked. Defaults to 86400 (24 hours)."
+              rules={{ required: true }}
+            />
+          </FormControl>
+        </FormGroup>
+      </CardContent>
+    </Card>
+  );
+}

client/apps/web/src/routes/agent-control/page.tsx

@@ -0,0 +1,22 @@
+import { SuspenseLoader } from "@trenova/shared/components/component-loader";
+import { AdminPageLayout } from "@/components/navigation/sidebar-layout";
+import { PageHeader } from "@/components/page-header";
+import { lazy } from "react";
+
+const AgentControlForm = lazy(() => import("./_components/agent-control-form"));
+
+export function AgentControlPage() {
+  return (
+    <AdminPageLayout>
+      <PageHeader
+        title="Agent Control"
+        description="Configure the billing exception agent — enablement, shadow mode, and how long proposals wait for a human decision"
+      />
+      <SuspenseLoader>
+        <div className="p-4">
+          <AgentControlForm />
+        </div>
+      </SuspenseLoader>
+    </AdminPageLayout>
+  );
+}

client/apps/web/src/types/agent-control.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+const HOUR_IN_SECONDS = 3600;
+const MIN_DECISION_TIMEOUT = 5 * 60;
+const MAX_DECISION_TIMEOUT = 7 * 24 * HOUR_IN_SECONDS;
+
+export const agentControlSchema = z.object({
+  billingAgentEnabled: z.boolean(),
+  shadowMode: z.boolean(),
+  decisionTimeoutSeconds: z
+    .number({ message: "Decision timeout is required" })
+    .int("Decision timeout must be a whole number of seconds")
+    .min(MIN_DECISION_TIMEOUT, "Decision timeout must be at least 5 minutes")
+    .max(MAX_DECISION_TIMEOUT, "Decision timeout cannot exceed 7 days"),
+});
+
+export type AgentControlFormValues = z.infer<typeof agentControlSchema>;

client/packages/shared/src/types/permission.ts

@@ -162,6 +162,10 @@ export const Resource = {
   SettlementControl: "settlement_control",
   DashControl: "dash_control",
   DriverPortal: "driver_portal",
+  AgentRun: "agent_run",
+  AgentProposal: "agent_proposal",
+  AgentException: "agent_exception",
+  AgentControl: "agent_control",
 } as const;
 
 export type ResourceType = (typeof Resource)[keyof typeof Resource];