@graph8/sdk 0.362.0 → 0.373.0

package/blocks/agents/components/agent-approvals.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+/**
+ * AgentApprovals: the approvals inbox for everything agents ask permission for. Three parts:
+ *   Oversight  what needs you now (approvals, blockers) and what agents fixed on their own.
+ *   Waiting    each pending approval with Approve (lets the agent act: external, ConfirmSpendDialog), Reject, or Request changes
+ *              (sends your feedback back instead of deciding).
+ *   History    decided approvals, filterable by decision, each with its signed receipts (who contributed what).
+ * Approvals that gate a Work coordination action cannot be decided with an API key; the error is shown as is.
+ *
+ * SDK operations, in order:
+ *   1. getAgentOversight           GET  /agent/oversight?limit=20                              (read)
+ *   2. listAgentApprovals          GET  /agent/approvals                                       (read)  pending
+ *   3. decideAgentApproval         POST /agent/approvals/{approval_id}/decide { decision }     (write; approving is confirmed as external)
+ *   4. requestAgentApprovalChanges POST /agent/approvals/{approval_id}/request-changes { feedback }   (write)
+ *   5. listAgentApprovalHistory    GET  /agent/approvals/history?decision                      (read)
+ *   6. getAgentApprovalReceipts    GET  /agent/approvals/{approval_id}/receipts                (read)
+ */
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+
+export interface AgentApprovalsProps {
+  /** Open the run an approval belongs to. */
+  onOpenRun?: (runId: string) => void;
+  className?: string;
+}
+
+interface Approval { id: string; summary: string; risk_level: string; work_item_id: string; decision?: string | null; is_expired?: boolean; decided_at?: string | null; decided_by?: string | null; requested_at?: string | null }
+interface Receipt { id: string; action: string; entity_type: string; entity_id: string; contributed_by_user_id?: string | null; contributed_by_role_at_time?: string | null }
+// The only decision words the history filter accepts (agent_router.py).
+const DECISIONS: Array<[string, string]> = [["", "Any decision"], ["approve", "Approved"], ["reject", "Rejected"], ["edit_and_approve", "Edited and approved"], ["dismiss", "Dismissed"]];
+/** Rows per kind the oversight feed returns; a full kind means there may be more. */
+const OVERSIGHT_LIMIT = 20;
+const when = (v?: string | null): string => (v ? new Date(v).toLocaleString() : "");
+const enc = encodeURIComponent;
+
+function Receipts({ approvalId }: { approvalId: string }) {
+  const q = useG8Query((signal) => g8Get(`/agent/approvals/${enc(approvalId)}/receipts`, undefined, { signal }), [approvalId]);
+  const rows = bodyOf<{ receipts?: Receipt[] }>(q.data).receipts ?? [];
+  if (q.error) return <ApiError error={q.error} compact title="Could not load the receipts" onRetry={() => void q.refetch()} />;
+  if (q.loading && !q.data) return <Skeleton className="h-8 w-full" />;
+  if (rows.length === 0) return <p className="text-xs text-muted-foreground">No receipts were signed for this approval.</p>;
+  return <ul className="divide-y rounded-md border text-xs" aria-label="Receipts">{rows.map((r) => <li key={r.id} className="px-3 py-1.5">{r.action} on {r.entity_type} {r.entity_id}<span className="ml-2 text-muted-foreground">{r.contributed_by_user_id ?? "system"}{r.contributed_by_role_at_time ? `, ${r.contributed_by_role_at_time}` : ""}</span></li>)}</ul>;
+}
+
+export function AgentApprovals({ onOpenRun, className }: AgentApprovalsProps) {
+  const [decision, setDecision] = useState("");
+  const [approving, setApproving] = useState<Approval | null>(null);
+  const [changes, setChanges] = useState<{ approval: Approval; feedback: string } | null>(null);
+  const [showReceipts, setShowReceipts] = useState<string | null>(null);
+  const oversight = useG8Query((signal) => g8Get("/agent/oversight", { limit: OVERSIGHT_LIMIT }, { signal }), []);
+  const pending = useG8Query((signal) => g8Get("/agent/approvals", undefined, { signal }), []);
+  const history = useG8Query((signal) => g8Get("/agent/approvals/history", { decision: decision || undefined }, { signal }), [decision]);
+  const waiting = listOf<Approval>(pending.data).filter((a) => !a.decision && !a.is_expired);
+  const decided = listOf<Approval>(history.data);
+  const ov = bodyOf<{ approvals?: unknown[]; blockers?: Array<{ title?: string; summary?: string }>; autonomous_fixes?: Array<{ title?: string; summary?: string }> }>(oversight.data);
+  const refresh = () => { void pending.refetch(); void history.refetch(); void oversight.refetch(); };
+
+  const decide = useG8Mutation((v: { id: string; decision: "approve" | "reject" }) => g8Post(`/agent/approvals/${enc(v.id)}/decide`, { decision: v.decision }), { onSuccess: () => { setApproving(null); refresh(); }, onError: () => setApproving(null) });
+  const ask = useG8Mutation((v: { id: string; feedback: string }) => g8Post(`/agent/approvals/${enc(v.id)}/request-changes`, { feedback: v.feedback }), { onSuccess: () => { setChanges(null); refresh(); } });
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <SectionCard title="Needs you" description="Approvals and blockers across all agents, and what agents fixed themselves">
+        {oversight.error ? <ApiError error={oversight.error} title="Could not load the oversight feed" onRetry={() => void oversight.refetch()} /> : null}
+        {oversight.loading && !oversight.data ? <Skeleton className="h-10 w-full" /> : null}
+        {oversight.data ? (
+          <dl className="grid grid-cols-3 gap-3 text-sm" data-testid="oversight">
+            <div><dt className="text-xs text-muted-foreground">Approvals</dt><dd>{(ov.approvals ?? []).length}</dd></div>
+            <div><dt className="text-xs text-muted-foreground">Blockers</dt><dd>{(ov.blockers ?? []).length}</dd></div>
+            <div><dt className="text-xs text-muted-foreground">Fixed on their own</dt><dd>{(ov.autonomous_fixes ?? []).length}</dd></div>
+          </dl>
+        ) : null}
+        {[ov.approvals, ov.blockers, ov.autonomous_fixes].some((l) => (l ?? []).length >= OVERSIGHT_LIMIT) ? <p className="mt-2 text-xs text-muted-foreground">Showing the first {OVERSIGHT_LIMIT} of each kind. Older items are in the history below.</p> : null}
+        {(ov.blockers ?? []).length ? <ul className="mt-3 list-disc pl-5 text-sm">{(ov.blockers ?? []).map((b, i) => <li key={i}>{b.title ?? b.summary}</li>)}</ul> : null}
+      </SectionCard>
+
+      <SectionCard title={`Waiting for a decision (${waiting.length})`} flush>
+        {pending.error ? <div className="p-3"><ApiError error={pending.error} title="Could not load the approvals" onRetry={() => void pending.refetch()} /></div> : null}
+        {pending.loading && !pending.data ? <Skeleton className="m-3 h-10" /> : null}
+        <ul className="divide-y">
+          {waiting.map((a) => (
+            <li key={a.id} data-testid={`approval-${a.id}`} className="flex flex-wrap items-center justify-between gap-2 px-4 py-2 text-sm">
+              <span>{a.summary}<span className="ml-2 text-xs text-muted-foreground">risk: {a.risk_level}</span>{onOpenRun ? <button type="button" className="ml-2 text-xs underline" onClick={() => onOpenRun(a.work_item_id)}>Open run</button> : null}</span>
+              <span className="flex gap-2">
+                <Button size="sm" variant="ghost" onClick={() => setChanges({ approval: a, feedback: "" })}>Request changes</Button>
+                <Button size="sm" variant="outline" disabled={decide.loading} onClick={() => void decide.mutate({ id: a.id, decision: "reject" })}>Reject</Button>
+                <Button size="sm" disabled={decide.loading} onClick={() => setApproving(a)}>Approve</Button>
+              </span>
+            </li>
+          ))}
+        </ul>
+        {!pending.loading && !pending.error && waiting.length === 0 ? <EmptyState compact title="Nothing is waiting" description="When an agent needs permission to act, it shows up here." /> : null}
+        {decide.error ? <div className="p-3"><ApiError error={decide.error} title="Could not record the decision" /></div> : null}
+      </SectionCard>
+
+      <SectionCard title="History" flush actions={<select aria-label="Decision" className="h-8 rounded-md border bg-background px-2 text-sm" value={decision} onChange={(e) => setDecision(e.target.value)}>{DECISIONS.map(([v, l]) => <option key={v} value={v}>{l}</option>)}</select>}>
+        {history.error ? <div className="p-3"><ApiError error={history.error} title="Could not load the history" onRetry={() => void history.refetch()} /></div> : null}
+        {history.loading && !history.data ? <Skeleton className="m-3 h-10" /> : null}
+        <ul className="divide-y">
+          {decided.map((a) => (
+            <li key={a.id} className="px-4 py-2 text-sm">
+              <div className="flex flex-wrap items-center justify-between gap-2">
+                <span>{a.summary}</span>
+                <span className="flex items-center gap-2"><StatusPill tone={toneForStatus(a.decision ?? "")} dot>{a.decision ?? "undecided"}</StatusPill><span className="text-xs text-muted-foreground">{when(a.decided_at ?? a.requested_at)}</span><Button size="sm" variant="ghost" aria-expanded={showReceipts === a.id} onClick={() => setShowReceipts(showReceipts === a.id ? null : a.id)}>Receipts</Button></span>
+              </div>
+              {showReceipts === a.id ? <div className="mt-2"><Receipts approvalId={a.id} /></div> : null}
+            </li>
+          ))}
+        </ul>
+        {!history.loading && !history.error && decided.length === 0 ? <EmptyState compact title="No decisions yet" /> : null}
+      </SectionCard>
+
+      <Dialog open={changes != null} onOpenChange={(o) => !o && setChanges(null)}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>Request changes</DialogTitle><DialogDescription>{changes?.approval.summary}</DialogDescription></DialogHeader>
+          <Textarea aria-label="Feedback" rows={4} placeholder="What should the agent change?" value={changes?.feedback ?? ""} onChange={(e) => setChanges((c) => c && { ...c, feedback: e.target.value })} />
+          {ask.error ? <ApiError error={ask.error} title="Could not send the feedback" /> : null}
+          <DialogFooter><Button variant="ghost" onClick={() => setChanges(null)}>Cancel</Button><Button loading={ask.loading} disabled={!changes?.feedback.trim()} onClick={() => changes && void ask.mutate({ id: changes.approval.id, feedback: changes.feedback.trim() })}>Send feedback</Button></DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <ConfirmSpendDialog open={approving != null} tier="external" title="Approve this action" description={approving?.summary}
+        confirmLabel="Approve" confirming={decide.loading} onConfirm={() => approving && void decide.mutate({ id: approving.id, decision: "approve" })} onCancel={() => setApproving(null)} />
+    </div>
+  );
+}

package/blocks/agents/components/agent-builder.tsx

@@ -21,6 +21,9 @@
 import { useEffect, useState } from "react";
 import { Button, Input, Label, Skeleton, Switch, Textarea } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { byPage, hasNextOf } from "@/g8/lib/paging";
+import { FirstNotice, LoadMore } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
@@ -37,6 +40,8 @@ export interface AgentBuilderProps {
   onSelect?: (agentId: string | null) => void;
   /** Called after a create, update or delete so the host can refresh its own lists. */
   onChanged?: () => void;
+  /** Hide the built-in agent list and "New agent" button when the host (for example AgentsScreen) provides its own. */
+  hideList?: boolean;
   className?: string;
 }
 
@@ -60,7 +65,12 @@ function Dial({ label, value, onChange, low, high }: { label: string; value: num
   );
 }
 
-export function AgentBuilder({ agentId: controlled, onSelect, onChanged, className }: AgentBuilderProps) {
+/** Agents per read; "Load more" appends the next page (the list used to stop silently at 50). */
+const AGENT_PAGE = 50;
+/** The voice presets API has no paging: a full read is announced under the select. */
+const VOICE_LIMIT = 100;
+
+export function AgentBuilder({ agentId: controlled, onSelect, onChanged, hideList, className }: AgentBuilderProps) {
   const [inner, setInner] = useState<string | null>(null);
   const selected = controlled !== undefined ? controlled : inner;
   const [creating, setCreating] = useState(false);
@@ -70,9 +80,13 @@ export function AgentBuilder({ agentId: controlled, onSelect, onChanged, classNa
   const [deleting, setDeleting] = useState(false);
 
   const choose = (id: string | null) => { setInner(id); setCreating(false); onSelect?.(id); };
-  const agents = useG8Query((signal) => g8Get("/voice/agents", { search: search.trim() || undefined, page_size: 50 }, { signal }), [search]);
+  const agents = useLoadMoreList(byPage<AgentSummary>(AGENT_PAGE, async (page, signal) => {
+    const env = await g8Get("/voice/agents", { search: search.trim() || undefined, page, page_size: AGENT_PAGE }, { signal });
+    const rows = listOf<AgentSummary>(env, "agents");
+    return { rows, hasNext: hasNextOf(env, AGENT_PAGE, rows.length) };
+  }), [search], { enabled: !hideList });
   const detail = useG8Query((signal) => g8Get(`/voice/agents/${selected}`, undefined, { signal }), [selected], { enabled: Boolean(selected) && !creating });
-  const voices = useG8Query((signal) => g8Get("/voice/voice-library/presets", { limit: 100 }, { signal }), []);
+  const voices = useG8Query((signal) => g8Get("/voice/voice-library/presets", { limit: VOICE_LIMIT }, { signal }), []);
 
   useEffect(() => {
     const agent = bodyOf<{ agent?: AgentDetail | null }>(detail.data).agent;
@@ -87,7 +101,7 @@ export function AgentBuilder({ agentId: controlled, onSelect, onChanged, classNa
     {
       onSuccess: (res) => {
         const id = bodyOf<{ agent?: { agent_id?: string } }>(res).agent?.agent_id;
-        void agents.refetch();
+        if (!hideList) void agents.refetch();
         // Keep the new id on the draft at once: a second click (or a retry after a later step fails) must update, never create a twin.
         if (!draft?.agent_id && id) { setDraft((d) => d && { ...d, agent_id: id }); choose(id); }
         else void detail.refetch();
@@ -96,17 +110,19 @@ export function AgentBuilder({ agentId: controlled, onSelect, onChanged, classNa
     },
   );
   const remove = useG8Mutation((id: string) => g8Delete(`/voice/agents/${id}`), {
-    onSuccess: () => { setDeleting(false); setDraft(null); choose(null); void agents.refetch(); onChanged?.(); },
+    onSuccess: () => { setDeleting(false); setDraft(null); choose(null); if (!hideList) void agents.refetch(); onChanged?.(); },
   });
 
-  const rows = listOf<AgentSummary>(agents.data, "agents");
+  const rows = agents.data ?? [];
   const presets = listOf<{ voice_id?: string; id?: string; name?: string; label?: string }>(voices.data, "items");
   const setPersona = (patch: Partial<AgentDetail["persona"]>) => setDraft((d) => d && { ...d, persona: { ...d.persona, ...patch } });
+  // The hook keeps the previous agent's data while the next one loads: until it arrives the old form must not be shown (or saved) as the new agent.
+  const stale = Boolean(draft?.agent_id && selected && draft.agent_id !== selected && !creating);
   const valid = Boolean(draft?.persona.agent_name.trim() && draft?.persona.persona.trim() && draft?.persona.description.trim() && draft?.role.trim());
 
   return (
-    <div className={`grid gap-4 md:grid-cols-[16rem_1fr] ${className ?? ""}`}>
-      <aside className="flex flex-col gap-2">
+    <div className={`grid gap-4 ${hideList ? "" : "md:grid-cols-[16rem_1fr]"} ${className ?? ""}`}>
+      {hideList ? null : <aside className="flex flex-col gap-2">
         <div className="flex gap-2">
           <Input aria-label="Search agents" placeholder="Search agents" value={search} onChange={(e) => setSearch(e.target.value)} />
           <Button size="sm" onClick={() => { setCreating(true); setDraft(blankDraft()); setSection("persona"); onSelect?.(null); }}>New agent</Button>
@@ -124,15 +140,17 @@ export function AgentBuilder({ agentId: controlled, onSelect, onChanged, classNa
             </li>
           ))}
         </ul>
+        <LoadMore shown={rows.length} noun="agents" hasMore={agents.hasMore} loading={agents.loadingMore} onLoadMore={agents.loadMore} />
         {!agents.loading && !agents.error && rows.length === 0 ? (
           <EmptyState title="No agents yet" description="An agent has a persona, a voice, knowledge and skills." />
         ) : null}
-      </aside>
+      </aside>}
 
       <section className="flex min-w-0 flex-col gap-3">
         {!draft && !creating ? <EmptyState title="Pick an agent" description="Choose one on the left or create a new agent." /> : null}
         {detail.error ? <ApiError error={detail.error} title="Could not load the agent" onRetry={() => void detail.refetch()} /> : null}
-        {draft ? (
+        {stale && !detail.error ? <Skeleton className="h-64 w-full" aria-label="Loading agent" /> : null}
+        {draft && !stale ? (
           <>
             <div role="tablist" className="flex gap-1 border-b">
               {SECTIONS.map((s) => (
@@ -165,6 +183,7 @@ export function AgentBuilder({ agentId: controlled, onSelect, onChanged, classNa
                     <option value="">Default voice</option>
                     {presets.map((v) => { const id = v.voice_id ?? v.id ?? ""; return <option key={id} value={id}>{v.name ?? v.label ?? id}</option>; })}
                   </select>
+                  <FirstNotice shown={presets.length} limit={VOICE_LIMIT} noun="voices" />
                 </div>
                 <div className="flex flex-col gap-1"><Label htmlFor="agent-inbound">Inbound call instructions</Label><Textarea id="agent-inbound" rows={3} value={draft.persona.inbound_instructions ?? ""} onChange={(e) => setPersona({ inbound_instructions: e.target.value || null })} /></div>
                 <div className="flex flex-col gap-1"><Label htmlFor="agent-outbound">Outbound call instructions</Label><Textarea id="agent-outbound" rows={3} value={draft.persona.outbound_instructions ?? ""} onChange={(e) => setPersona({ outbound_instructions: e.target.value || null })} /></div>

package/blocks/agents/components/agent-conversations.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+/**
+ * AgentConversations: the chat history of one agent. The list of its conversations (newest first, "Load more" up to the API's 100),
+ * a conversation's messages, rename, hand-over to a human and delete, plus a message box to talk to the agent yourself.
+ * Sending a message is billable and the agent may run its attached skills while answering, so it goes through ConfirmSpendDialog.
+ * Deleting a conversation is destructive and confirmed.
+ *
+ * SDK operations, in order:
+ *   1. listChatAgentConversations   POST   /voice/chat-agent/conversations { agent_id, limit }        (read, a POST with a body)
+ *   2. getChatAgentHistory          POST   /voice/chat-agent/history { agent_id, contact_id, session_id }   (read)
+ *   3. renameChatAgentConversation  PUT    /voice/chat-agent/conversations/{chat_id}/name?agent_id { name }  (write)
+ *   4. transferChatAgentConversation POST  /voice/chat-agent/conversations/{chat_id}/transfer-to-human       (write)
+ *   5. deleteChatAgentConversation  DELETE /voice/chat-agent/conversations/{chat_id}?agent_id       (destructive, ConfirmSpendDialog)
+ *   6. sendChatAgentMessage         POST   /voice/chat-agent/messages { agent_id, contact_id, message, session_id? }  (billable, ConfirmSpendDialog)
+ *
+ * The history route does not match on contact_id, so any stable string works; `contactId` lets a host pass the person's own id.
+ */
+import { useEffect, useState } from "react";
+import { MessageSquare } from "lucide-react";
+import { Button, Input, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import { LoadMore, useGrowingList } from "../lib/load-more";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface AgentConversationsProps {
+  agentId: string;
+  /** Sent as contact_id on messages and history reads. Default "sdk". */
+  contactId?: string;
+  className?: string;
+}
+
+interface Chat { id: string; name?: string; message_count?: number; updated_at?: string | null; created_at?: string | null }
+interface Msg { role?: string; content?: unknown; created_at?: string }
+
+const text = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : JSON.stringify(v));
+const when = (v?: string | null): string => (v ? new Date(v).toLocaleString() : "");
+
+function Transcript({ agentId, chat, contactId, refreshKey }: { agentId: string; chat: Chat; contactId: string; refreshKey: number }) {
+  const history = useG8Query((signal) => g8Post(`/voice/chat-agent/history`, { agent_id: agentId, contact_id: contactId, session_id: chat.id }, { signal }), [agentId, chat.id, contactId, refreshKey]);
+  const body = bodyOf<{ messages?: Msg[]; success?: boolean; error?: string }>(history.data);
+  const messages = listOf<Msg>(history.data, "messages", "items");
+  if (history.error) return <ApiError error={history.error} title="Could not load the conversation" onRetry={() => void history.refetch()} />;
+  if (history.loading && !history.data) return <Skeleton className="h-24 w-full" aria-label="Loading conversation" />;
+  if (body.success === false && body.error) return <p className="text-sm text-muted-foreground">{body.error}</p>;
+  if (!messages.length) return <p className="text-sm text-muted-foreground">No messages in this conversation yet.</p>;
+  return (
+    <ol className="flex flex-col gap-2" aria-label="Messages">
+      {messages.map((m, i) => (
+        <li key={i} className={`max-w-[85%] rounded-md border px-3 py-2 text-sm ${m.role === "user" ? "self-end bg-accent" : "self-start"}`}>
+          <span className="block text-xs text-muted-foreground">{m.role === "user" ? "Contact" : m.role === "assistant" ? "Agent" : (m.role ?? "")}</span>
+          <span className="whitespace-pre-wrap">{text(m.content)}</span>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+export function AgentConversations({ agentId, contactId = "sdk", className }: AgentConversationsProps) {
+  const brand = useBrand();
+  const [openId, setOpenId] = useState<string | null>(null);
+  const [renaming, setRenaming] = useState<{ id: string; name: string } | null>(null);
+  const [deleting, setDeleting] = useState<Chat | null>(null);
+  const [draft, setDraft] = useState("");
+  const [sending, setSending] = useState<string | null>(null);
+  const [turn, setTurn] = useState(0);
+  const list = useGrowingList<Chat>(async (limit, signal) => listOf<Chat>(await g8Post("/voice/chat-agent/conversations", { agent_id: agentId, limit }, { signal }), "chats", "items", "conversations"), [agentId], { pageSize: 25, max: 100 });
+  useEffect(() => { setOpenId(null); setRenaming(null); setDeleting(null); setDraft(""); setSending(null); }, [agentId]);
+  const open = list.items.find((c) => c.id === openId) ?? (openId ? { id: openId } : null);
+  const enc = encodeURIComponent;
+
+  const rename = useG8Mutation((v: { id: string; name: string }) => g8Put(`/voice/chat-agent/conversations/${enc(v.id)}/name`, { name: v.name }, { query: { agent_id: agentId } }), { onSuccess: () => { setRenaming(null); list.reload(); } });
+  const handover = useG8Mutation((id: string) => g8Post(`/voice/chat-agent/conversations/${enc(id)}/transfer-to-human`, {}), { onSuccess: () => list.reload() });
+  const remove = useG8Mutation((id: string) => g8Delete(`/voice/chat-agent/conversations/${enc(id)}`, { query: { agent_id: agentId } }), { onSuccess: (_r, id) => { setDeleting(null); if (openId === id) setOpenId(null); list.reload(); } });
+  const send = useG8Mutation(async (message: string) => {
+    const res = await g8Post("/voice/chat-agent/messages", { agent_id: agentId, contact_id: contactId, message, ...(openId ? { session_id: openId } : {}) });
+    return bodyOf<{ session_id?: string }>(res).session_id ?? null;
+  }, { onSuccess: (sid) => { setSending(null); setDraft(""); if (sid) setOpenId(sid); setTurn((t) => t + 1); list.reload(); }, onError: () => setSending(null) });
+
+  return (
+    <div className={`grid gap-4 lg:grid-cols-[18rem_1fr] ${className ?? ""}`}>
+      <div className="flex flex-col gap-2">
+        <div className="flex items-center justify-between"><h3 className="text-sm font-medium">Conversations</h3><Button size="sm" variant="outline" onClick={() => setOpenId(null)}>New chat</Button></div>
+        {list.error ? <ApiError error={list.error} title="Could not load conversations" onRetry={list.reload} /> : null}
+        {list.loading ? <Skeleton className="h-16 w-full" aria-label="Loading conversations" /> : null}
+        <ul className="divide-y rounded-md border">
+          {list.items.map((c) => (
+            <li key={c.id} className={openId === c.id ? "bg-accent" : ""}>
+              <button type="button" data-testid={`chat-${c.id}`} className="block w-full px-3 py-2 text-left text-sm" onClick={() => setOpenId(c.id)}>
+                <span className="block truncate font-medium">{c.name || "Chat"}</span>
+                <span className="block text-xs text-muted-foreground">{c.message_count ?? 0} messages, {when(c.updated_at ?? c.created_at)}</span>
+              </button>
+            </li>
+          ))}
+        </ul>
+        {!list.loading && !list.error && list.items.length === 0 ? <EmptyState compact icon={<MessageSquare strokeWidth={1.5} />} title="No conversations yet" description="Send a message to start one." /> : null}
+        <LoadMore list={list} noun="conversations" />
+      </div>
+      <div className="flex min-w-0 flex-col gap-3">
+        {open ? (
+          <>
+            <div className="flex flex-wrap items-center gap-2">
+              {renaming?.id === open.id ? (
+                <>
+                  <Input aria-label="Conversation name" className="max-w-xs" value={renaming.name} onChange={(e) => setRenaming({ id: open.id, name: e.target.value })} />
+                  <Button size="sm" loading={rename.loading} disabled={!renaming.name.trim()} onClick={() => void rename.mutate(renaming)}>Save name</Button>
+                  <Button size="sm" variant="ghost" onClick={() => setRenaming(null)}>Cancel</Button>
+                </>
+              ) : (
+                <>
+                  <h3 className="text-sm font-medium">{(open as Chat).name || "Conversation"}</h3>
+                  <Button size="sm" variant="outline" onClick={() => setRenaming({ id: open.id, name: (open as Chat).name ?? "" })}>Rename</Button>
+                  <Button size="sm" variant="outline" loading={handover.loading} onClick={() => void handover.mutate(open.id)}>Hand over to a human</Button>
+                  <Button size="sm" variant="ghost" onClick={() => setDeleting(open as Chat)}>Delete</Button>
+                </>
+              )}
+            </div>
+            {rename.error ? <ApiError error={rename.error} title="Could not rename the conversation" /> : null}
+            {handover.error ? <ApiError error={handover.error} title="Could not hand the conversation over" /> : null}
+            {handover.data ? <p role="status" className="text-sm text-muted-foreground">A person will pick this conversation up.</p> : null}
+            <Transcript agentId={agentId} chat={open as Chat} contactId={contactId} refreshKey={turn} />
+          </>
+        ) : <p className="text-sm text-muted-foreground">Pick a conversation, or type below to start a new one.</p>}
+        <div className="flex flex-col gap-2 border-t pt-3">
+          <Textarea aria-label="Message to the agent" rows={3} value={draft} onChange={(e) => setDraft(e.target.value)} placeholder="Say something to this agent" />
+          {send.error ? <ApiError error={send.error} title="Could not send the message" /> : null}
+          <Button className="self-end" disabled={!draft.trim()} onClick={() => setSending(draft.trim())}>Send message</Button>
+        </div>
+      </div>
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the conversation" /> : null}
+      <ConfirmSpendDialog open={sending != null} tier="billable" title="Send a message to this agent" description={`The agent answers with the model and may run the skills attached to it, which can reach outside ${brand.name}. Each turn spends credits.`}
+        confirmLabel="Send" confirming={send.loading} onConfirm={() => sending && void send.mutate(sending)} onCancel={() => setSending(null)} />
+      <ConfirmSpendDialog open={deleting != null} tier="destructive" title={`Delete "${deleting?.name || "this conversation"}"`} description="The messages are removed for everyone." affected={1}
+        confirmLabel="Delete" confirming={remove.loading} onConfirm={() => deleting && void remove.mutate(deleting.id)} onCancel={() => setDeleting(null)} />
+    </div>
+  );
+}

package/blocks/agents/components/agent-knowledge-panel.tsx

@@ -25,6 +25,7 @@ import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
 import { listOf } from "../lib/agent-types";
+import { plural } from "@/g8/lib/plural";
 
 export interface AgentKnowledgePanelProps {
   agentId: string;
@@ -89,7 +90,7 @@ export function AgentKnowledgePanel({ agentId, useCompanyKnowledge, onToggleComp
 
       <div className="flex flex-col gap-2">
         <div className="flex items-center justify-between">
-          <h3 className="text-sm font-semibold">This agent&apos;s documents</h3>
+          <h3 className="text-sm font-medium">This agent&apos;s documents</h3>
           <Button size="sm" variant="outline" onClick={() => fileInput.current?.click()}>Upload documents</Button>
           <input ref={fileInput} type="file" multiple hidden aria-label="Choose documents" accept=".pdf,.docx,.txt,.md" onChange={(e) => onPick(e.target.files)} />
         </div>
@@ -112,7 +113,7 @@ export function AgentKnowledgePanel({ agentId, useCompanyKnowledge, onToggleComp
       </div>
 
       <div className="flex flex-col gap-2">
-        <h3 className="text-sm font-semibold">Company knowledge</h3>
+        <h3 className="text-sm font-medium">Company knowledge</h3>
         <form className="flex gap-2" onSubmit={(e) => { e.preventDefault(); setSubmitted(query.trim()); }}>
           <Input aria-label="Search company knowledge" placeholder="Search what the agent can draw on" value={query} onChange={(e) => setQuery(e.target.value)} />
           <Button type="submit" size="sm" variant="outline" disabled={!query.trim()}>Search</Button>
@@ -132,7 +133,7 @@ export function AgentKnowledgePanel({ agentId, useCompanyKnowledge, onToggleComp
 
       {upload.error ? <ApiError error={upload.error} title="Could not upload" /> : null}
       {remove.error ? <ApiError error={remove.error} title="Could not remove the document" /> : null}
-      <ConfirmSpendDialog open={pending != null} tier="billable" title={`Index ${pending?.length ?? 0} document${pending?.length === 1 ? "" : "s"}`}
+      <ConfirmSpendDialog open={pending != null} tier="billable" title={`Index ${plural(pending?.length ?? 0, "document")}`}
         description="The text is extracted and embedded with a paid model so the agent can search it."
         estimatedCredits={(pending?.length ?? 0) * creditsPerFile} confirmLabel="Upload" confirming={upload.loading}
         onConfirm={() => pending && void upload.mutate(pending)} onCancel={() => setPending(null)} />

package/blocks/agents/components/agent-operators.tsx

@@ -0,0 +1,164 @@
+"use client";
+
+/**
+ * AgentOperators: the autonomous operators that work in your workspace without being asked (each monitors something on a schedule,
+ * records findings, and acts only as far as its trust dial allows). A summary, the bench (turn each on or off), and for the open
+ * operator: Skills (the trust dial per skill: off, detect, propose or auto), Findings, Activity, Health and Scorecard.
+ * Turning an operator on, and raising a trust dial, start work that proceeds on its own and spends credits, so both go through
+ * ConfirmSpendDialog (billable). Deciding an operator's proposed fix (which changes your data) is not offered here; it stays in graph8.
+ *
+ * SDK operations, in order:
+ *   1. getAgentOperatorsSummary   GET /agent/operators/summary                              (read)
+ *   2. listAgentOperators         GET /agent/operators                                      (read)
+ *   3. getAgentOperatorStatus     GET /agent/operators/{operator}/status                    (read)
+ *   4. setAgentOperatorEnabled    PUT /agent/operators/{operator}/enabled { enabled }       (billable, ConfirmSpendDialog)
+ *   5. listAgentOperatorSkills    GET /agent/operators/{operator}/skills                    (read)
+ *   6. setAgentOperatorTrustDial  PUT /agent/operators/{operator}/skills/{skill_key} { autonomy }   (billable, ConfirmSpendDialog)
+ *   7. listAgentOperatorFindings  GET /agent/operators/{operator}/findings                  (read)
+ *   8. listAgentOperatorActivity  GET /agent/operators/{operator}/activity?limit            (read)  "Load more" grows the limit
+ *   9. getAgentOperatorHealth     GET /agent/operators/{operator}/health                    (read)
+ *  10. getAgentOperatorScorecard  GET /agent/operators/{operator}/scorecard                 (read)
+ */
+import { useState } from "react";
+import { Cpu } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get, g8Put } from "@/g8/lib/g8-client";
+import { FactList } from "../lib/facts";
+import { bodyOf, listOf } from "../lib/agent-types";
+import { LoadMore, useGrowingList } from "../lib/load-more";
+
+export interface AgentOperatorsProps {
+  className?: string;
+}
+
+interface Operator { operator: string; title?: string; persona?: string; enabled?: boolean; has_run?: boolean; findings_total?: number; findings_critical?: number; detection?: boolean }
+interface OperatorSkill { key: string; name?: string; title?: string; description?: string; autonomy?: string; default_autonomy?: string }
+const LEVELS = ["OFF", "DETECT", "PROPOSE", "AUTO"] as const;
+type Level = (typeof LEVELS)[number];
+const enc = encodeURIComponent;
+
+function Skills({ operator, onAsk }: { operator: string; onAsk: (v: { key: string; label: string; autonomy: Level }) => void }) {
+  const skills = useG8Query((signal) => g8Get(`/agent/operators/${enc(operator)}/skills`, undefined, { signal }), [operator]);
+  const rows = listOf<OperatorSkill>(skills.data, "items", "skills");
+  if (skills.error) return <ApiError error={skills.error} title="Could not load the skills" onRetry={() => void skills.refetch()} />;
+  if (skills.loading && !skills.data) return <Skeleton className="h-16 w-full" />;
+  if (rows.length === 0) return <p className="text-sm text-muted-foreground">This operator has no skills to tune.</p>;
+  return (
+    <ul className="divide-y rounded-md border" aria-label="Operator skills">
+      {rows.map((s) => (
+        <li key={s.key} className="flex flex-wrap items-center justify-between gap-2 px-3 py-2 text-sm">
+          <span><span className="font-medium">{s.name ?? s.title ?? s.key}</span>{s.description ? <span className="block text-xs text-muted-foreground">{s.description}</span> : null}</span>
+          <select aria-label={`Autonomy for ${s.name ?? s.title ?? s.key}`} className="h-8 rounded-md border bg-background px-2 text-sm" value={(s.autonomy ?? s.default_autonomy ?? "OFF").toUpperCase()}
+            onChange={(e) => onAsk({ key: s.key, label: s.name ?? s.title ?? s.key, autonomy: e.target.value as Level })}>
+            {LEVELS.map((l) => <option key={l} value={l}>{l.toLowerCase()}</option>)}
+          </select>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function Activity({ operator }: { operator: string }) {
+  const list = useGrowingList<Record<string, unknown>>(async (limit, signal) => listOf<Record<string, unknown>>(await g8Get(`/agent/operators/${enc(operator)}/activity`, { limit }, { signal }), "items"), [operator], { pageSize: 25, max: 200 });
+  if (list.error) return <ApiError error={list.error} title="Could not load the activity" onRetry={list.reload} />;
+  if (list.loading) return <Skeleton className="h-16 w-full" />;
+  if (list.items.length === 0) return <p className="text-sm text-muted-foreground">Nothing has been decided or fixed yet.</p>;
+  return (
+    <div className="flex flex-col gap-2">
+      <ul className="divide-y rounded-md border" aria-label="Operator activity">
+        {list.items.map((r, i) => <li key={String(r.task_id ?? r.id ?? i)} className="px-3 py-2 text-sm">{String(r.title ?? r.summary ?? r.check_id ?? "Activity")}<span className="block text-xs text-muted-foreground">{String(r.resolution ?? r.status ?? "")} {r.at || r.created_at ? new Date(String(r.at ?? r.created_at)).toLocaleString() : ""}</span></li>)}
+      </ul>
+      <LoadMore list={list} noun="events" />
+    </div>
+  );
+}
+
+function Findings({ operator }: { operator: string }) {
+  const q = useG8Query((signal) => g8Get(`/agent/operators/${enc(operator)}/findings`, undefined, { signal }), [operator]);
+  const rows = listOf<Record<string, unknown>>(q.data, "items", "findings");
+  if (q.error) return <ApiError error={q.error} title="Could not load the findings" onRetry={() => void q.refetch()} />;
+  if (q.loading && !q.data) return <Skeleton className="h-16 w-full" />;
+  if (rows.length === 0) return <p className="text-sm text-muted-foreground">No open findings.</p>;
+  return <ul className="divide-y rounded-md border" aria-label="Findings">{rows.map((r, i) => <li key={String(r.id ?? r.check_id ?? i)} className="flex items-center justify-between gap-2 px-3 py-2 text-sm"><span>{String(r.title ?? r.summary ?? r.check_id ?? "Finding")}</span>{r.severity ? <StatusPill tone={String(r.severity) === "critical" ? "negative" : "warning"}>{String(r.severity)}</StatusPill> : null}</li>)}</ul>;
+}
+
+function Facts({ path }: { path: string }) {
+  const q = useG8Query((signal) => g8Get(path, undefined, { signal }), [path]);
+  if (q.error) return <ApiError error={q.error} title="Could not load this" onRetry={() => void q.refetch()} />;
+  if (q.loading && !q.data) return <Skeleton className="h-16 w-full" />;
+  return <FactList data={bodyOf(q.data)} />;
+}
+
+export function AgentOperators({ className }: AgentOperatorsProps) {
+  const [open, setOpen] = useUrlState("operator", "");
+  const [enabling, setEnabling] = useState<{ operator: Operator; enabled: boolean } | null>(null);
+  const [dial, setDial] = useState<{ key: string; label: string; autonomy: Level } | null>(null);
+  const [dialKey, setDialKey] = useState(0);
+  const summary = useG8Query((signal) => g8Get("/agent/operators/summary", undefined, { signal }), []);
+  const bench = useG8Query((signal) => g8Get("/agent/operators", undefined, { signal }), []);
+  const rows = listOf<Operator>(bench.data, "items", "operators");
+  const current = rows.find((o) => o.operator === open);
+  const sum = bodyOf<Record<string, number>>(summary.data);
+
+  const toggle = useG8Mutation((v: { operator: string; enabled: boolean }) => g8Put(`/agent/operators/${enc(v.operator)}/enabled`, { enabled: v.enabled }), { onSuccess: () => { setEnabling(null); void bench.refetch(); void summary.refetch(); }, onError: () => setEnabling(null) });
+  const setLevel = useG8Mutation((v: { operator: string; key: string; autonomy: Level }) => g8Put(`/agent/operators/${enc(v.operator)}/skills/${enc(v.key)}`, { autonomy: v.autonomy }), { onSuccess: () => { setDial(null); setDialKey((k) => k + 1); }, onError: () => { setDial(null); setDialKey((k) => k + 1); } });
+
+  const list = (
+    <div className="flex flex-col gap-3">
+      {bench.error ? <ApiError error={bench.error} title="Could not load the operators" onRetry={() => void bench.refetch()} /> : null}
+      {bench.loading && !bench.data ? <Skeleton className="h-20 w-full" aria-label="Loading operators" /> : null}
+      <ul className="divide-y rounded-md border">
+        {rows.map((o) => (
+          <li key={o.operator} className={`flex items-center gap-2 px-3 py-2 ${open === o.operator ? "bg-accent" : ""}`}>
+            <button type="button" data-testid={`operator-${o.operator}`} className="min-w-0 flex-1 text-left text-sm" onClick={() => setOpen(o.operator)}>
+              <span className="block truncate font-medium">{o.title ?? o.operator}</span>
+              <span className="block truncate text-xs text-muted-foreground">{o.detection === false ? "Always on" : `${o.findings_total ?? 0} findings, ${o.findings_critical ?? 0} critical`}</span>
+            </button>
+            {o.detection === false ? <StatusPill tone="positive" dot>on</StatusPill> : (
+              <Button size="sm" variant={o.enabled ? "outline" : "default"} onClick={() => setEnabling({ operator: o, enabled: !o.enabled })}>{o.enabled ? "Turn off" : "Turn on"}</Button>
+            )}
+          </li>
+        ))}
+      </ul>
+      {!bench.loading && !bench.error && rows.length === 0 ? <EmptyState icon={<Cpu strokeWidth={1.5} />} title="No operators" description="Operators appear here once the workspace has them." /> : null}
+      {toggle.error ? <ApiError error={toggle.error} title="Could not change the operator" /> : null}
+    </div>
+  );
+
+  const detail = open ? (
+    <DetailPanel title={current?.title ?? open} subtitle={current?.persona} onClose={() => setOpen("")}
+      badges={current ? <StatusPill tone={current.enabled ? "positive" : "neutral"} dot>{current.enabled ? "on" : "off"}</StatusPill> : undefined}
+      tabs={current?.detection === false ? [{ id: "status", label: "Status", content: <Facts path={`/agent/operators/${enc(open)}/status`} /> }] : [
+        { id: "skills", label: "Skills", content: <><Skills key={`${open}:${dialKey}`} operator={open} onAsk={setDial} />{setLevel.error ? <ApiError error={setLevel.error} title="Could not change the trust dial" /> : null}</> },
+        { id: "findings", label: "Findings", content: <Findings operator={open} /> },
+        { id: "activity", label: "Activity", content: <Activity operator={open} /> },
+        { id: "health", label: "Health", content: <Facts path={`/agent/operators/${enc(open)}/health`} /> },
+        { id: "scorecard", label: "Scorecard", content: <Facts path={`/agent/operators/${enc(open)}/scorecard`} /> },
+        { id: "status", label: "Status", content: <Facts path={`/agent/operators/${enc(open)}/status`} /> },
+      ]} />
+  ) : null;
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <StatStrip loading={summary.loading && !summary.data} items={summary.error ? [] : Object.entries(sum).filter(([, v]) => typeof v === "number").slice(0, 5).map(([k, v]) => ({ label: k.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase()), value: String(v) }))} />
+      {summary.error ? <ApiError compact error={summary.error} title="Could not load the summary" onRetry={() => void summary.refetch()} /> : null}
+      <SplitView list={list} detail={detail} detailOpen={Boolean(open)} onCloseDetail={() => setOpen("")} detailWidth="lg" />
+      <ConfirmSpendDialog open={enabling != null} tier="billable" title={enabling?.enabled ? `Turn on ${enabling.operator.title ?? enabling.operator.operator}` : `Turn off ${enabling?.operator.title ?? enabling?.operator.operator ?? "operator"}`}
+        description={enabling?.enabled ? "Its monitors start running on a schedule and spend credits as they work, without being asked." : "Its monitors stop. Findings already recorded stay."}
+        confirmLabel={enabling?.enabled ? "Turn on" : "Turn off"} confirming={toggle.loading} onConfirm={() => enabling && void toggle.mutate({ operator: enabling.operator.operator, enabled: enabling.enabled })} onCancel={() => setEnabling(null)} />
+      <ConfirmSpendDialog open={dial != null} tier="billable" title={`Set ${dial?.label ?? "skill"} to ${dial?.autonomy.toLowerCase() ?? ""}`}
+        description="The trust dial decides how far this skill may go on its own when it finds something. Higher settings act without asking and spend credits."
+        confirmLabel="Set dial" confirming={setLevel.loading} onConfirm={() => dial && open && void setLevel.mutate({ operator: open, key: dial.key, autonomy: dial.autonomy })} onCancel={() => { setDial(null); setDialKey((k) => k + 1); }} />
+    </div>
+  );
+}