@graph8/sdk 0.362.0 → 0.373.0

package/blocks/agents/components/agent-run-detail.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+/**
+ * AgentRunDetail: one agent run in full. Title, status, agent, current step, next action, credits against the budget,
+ * created and completed times, the approvals this run is waiting on (approve or reject), and Cancel while it is live.
+ * The run is polled until it is terminal (the API has no streams).
+ *
+ * SDK operations, in order:
+ *   1. getAgentRun         GET  /agent/runs/{run_id}                          (read)  polled
+ *   2. listAgentApprovals  GET  /agent/approvals                              (read)  this run's pending ones
+ *   3. decideAgentApproval POST /agent/approvals/{approval_id}/decide { decision }   (write; approving lets the run act: ConfirmSpendDialog, external)
+ *   4. cancelAgentRun      POST /agent/runs/{run_id}/cancel                   (destructive, ConfirmSpendDialog)
+ *   5. steerAgentWorkItem  POST /agent/work-items/{work_item_id}/steer { client_turn_id, instruction }   (write; while the run is live)
+ *      The same client_turn_id is reused when a send is retried, so an instruction is never applied twice.
+ * Approvals that gate a Work coordination action cannot be decided with an API key: the error is shown as is.
+ */
+import { useEffect, useRef, useState } from "react";
+import { Button, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+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 { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import type { AgentRun } from "../lib/agent-types";
+import { isTerminalRun } from "./agent-runs";
+
+export interface AgentRunDetailProps {
+  runId: string;
+  /** Poll interval in ms. Default 3000. */
+  pollMs?: number;
+  /** Called after a cancel or a decision so the host can refresh its run list. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+interface Approval { id: string; summary: string; risk_level: string; work_item_id: string; decision?: string | null; is_expired?: boolean }
+
+const when = (v?: string | null): string => (v ? new Date(v).toLocaleString() : "");
+
+export function AgentRunDetail({ runId, pollMs = 3000, onChanged, className }: AgentRunDetailProps) {
+  const [cancelling, setCancelling] = useState(false);
+  const [approving, setApproving] = useState<Approval | null>(null);
+  const [deciding, setDeciding] = useState<string | null>(null);
+  const [steerText, setSteerText] = useState("");
+  const turnId = useRef<string | null>(null);
+  const poll = useJobPoll<AgentRun>((signal) => g8Get<AgentRun>(`/agent/runs/${encodeURIComponent(runId)}`, undefined, { signal }).then((r) => bodyOf<AgentRun>(r)), {
+    isTerminal: isTerminalRun, intervalMs: pollMs, maxIntervalMs: pollMs * 4, onDone: () => onChanged?.(),
+  });
+  const approvals = useG8Query((signal) => g8Get("/agent/approvals", undefined, { signal }), [runId]);
+  useEffect(() => { poll.start(); setCancelling(false); setApproving(null); }, [runId]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { if (poll.attempts > 0) void approvals.refetch(); }, [poll.attempts]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const cancel = useG8Mutation(() => g8Post(`/agent/runs/${encodeURIComponent(runId)}/cancel`, {}), { onSuccess: () => { setCancelling(false); poll.start(); onChanged?.(); }, onError: () => setCancelling(false) });
+  const decide = useG8Mutation(async (v: { id: string; decision: "approve" | "reject" }) => {
+    setDeciding(v.id);
+    try { return await g8Post(`/agent/approvals/${encodeURIComponent(v.id)}/decide`, { decision: v.decision }); } finally { setDeciding(null); }
+  }, { onSuccess: () => { setApproving(null); void approvals.refetch(); onChanged?.(); }, onError: () => setApproving(null) });
+
+  const steer = useG8Mutation((instruction: string) => {
+    turnId.current ??= globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    return g8Post(`/agent/work-items/${encodeURIComponent(runId)}/steer`, { client_turn_id: turnId.current, instruction });
+  }, { onSuccess: () => { turnId.current = null; setSteerText(""); poll.start(); } });
+  useEffect(() => { setSteerText(""); turnId.current = null; steer.reset(); }, [runId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const run = poll.status?.work_item_id === runId ? poll.status : undefined;
+  const pending = listOf<Approval>(approvals.data).filter((a) => a.work_item_id === runId && !a.decision && !a.is_expired);
+  if (!run) return poll.error ? <ApiError error={poll.error} title="Could not load the run" onRetry={() => poll.start()} /> : <Skeleton className="h-40 w-full" aria-label="Loading run" />;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`} data-testid="run-detail">
+      <div className="flex flex-wrap items-center gap-2">
+        <StatusPill tone={toneForStatus(run.status)} dot>{run.status}</StatusPill>
+        {poll.polling ? <span className="text-xs text-muted-foreground">updating</span> : null}
+        {!isTerminalRun(run) ? <Button className="ml-auto" size="sm" variant="outline" onClick={() => setCancelling(true)}>Cancel run</Button> : null}
+      </div>
+      <KeyValueList columns={2} items={[
+        { label: "Title", value: run.title, wide: true },
+        { label: "Agent", value: run.agent_id, mono: true },
+        { label: "Run id", value: run.work_item_id, mono: true },
+        { label: "Current step", value: run.current_step },
+        { label: "Next action", value: run.next_action },
+        { label: "Credits", value: `${run.credits_spent ?? 0}${run.credit_budget ? ` of ${run.credit_budget}` : ""}` },
+        { label: "Started", value: when(run.created_at) },
+        { label: "Finished", value: when(run.completed_at) },
+      ]} />
+      {pending.length > 0 ? (
+        <section className="space-y-2 rounded-md border p-3" aria-label="Approvals" data-testid="run-approvals">
+          <h4 className="text-sm font-medium">Waiting for your decision ({pending.length})</h4>
+          {pending.map((a) => (
+            <div key={a.id} className="flex flex-wrap items-center justify-between gap-2 text-sm">
+              <span>{a.summary}<span className="ml-2 text-xs text-muted-foreground">risk: {a.risk_level}</span></span>
+              <span className="flex gap-2">
+                <Button size="sm" variant="outline" loading={deciding === a.id} disabled={deciding != null && deciding !== a.id} onClick={() => void decide.mutate({ id: a.id, decision: "reject" })}>Reject</Button>
+                <Button size="sm" disabled={deciding != null} onClick={() => setApproving(a)}>Approve</Button>
+              </span>
+            </div>
+          ))}
+        </section>
+      ) : null}
+      {!isTerminalRun(run) ? (
+        <section className="space-y-2" aria-label="Steer the run">
+          <Textarea aria-label="Instruction for the agent" rows={2} placeholder="Tell the agent what to do differently" value={steerText} onChange={(e) => { if (e.target.value !== steerText) turnId.current = null; setSteerText(e.target.value); }} />
+          <div className="flex justify-end"><Button size="sm" variant="outline" loading={steer.loading} disabled={!steerText.trim()} onClick={() => void steer.mutate(steerText.trim())}>Send instruction</Button></div>
+          {steer.error ? <ApiError error={steer.error} title="Could not send the instruction" /> : null}
+        </section>
+      ) : null}
+      {decide.error ? <ApiError error={decide.error} title="Could not record the decision" /> : null}
+      {cancel.error ? <ApiError error={cancel.error} title="Could not cancel the run" /> : null}
+      <ConfirmSpendDialog open={cancelling} tier="destructive" title={`Cancel "${run.title}"`} description="Work stops where it is. Steps already taken are not undone."
+        confirmLabel="Cancel run" confirming={cancel.loading} onConfirm={() => void cancel.mutate(undefined)} onCancel={() => setCancelling(false)} />
+      <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-runs.tsx

@@ -36,6 +36,13 @@ export interface AgentRunsProps {
   pageSize?: number;
   /** Poll interval for the selected run, in ms. Default 3000. */
   pollMs?: number;
+  /** Controlled selection (a run id). With it, the host owns which run is open (for example from the URL). */
+  selectedId?: string | null;
+  onSelectRun?: (runId: string | null) => void;
+  /** Hide the built-in detail box when the host shows the run elsewhere (see AgentRunDetail). */
+  hideDetail?: boolean;
+  /** Change this number to reload the list (for example after AgentRunDetail cancelled a run). */
+  refreshKey?: number;
   className?: string;
 }
 
@@ -46,28 +53,30 @@ const TERMINAL = new Set(["completed", "succeeded", "failed", "cancelled", "canc
 export const isTerminalRun = (r: Pick<AgentRun, "status"> | undefined): boolean => TERMINAL.has(String(r?.status ?? "").toLowerCase());
 const STATUSES = ["running", "queued", "completed", "failed", "cancelled"];
 
-export function AgentRuns({ agentId, pageSize = 20, pollMs = 3000, className }: AgentRunsProps) {
+export function AgentRuns({ agentId, pageSize = 20, pollMs = 3000, selectedId, onSelectRun, hideDetail, refreshKey, className }: AgentRunsProps) {
   const [status, setStatus] = useState("");
   const [limit, setLimit] = useState(pageSize);
-  const [selected, setSelected] = useState<string | null>(null);
+  const [innerSel, setInnerSel] = useState<string | null>(null);
+  const selected = selectedId !== undefined ? selectedId : innerSel;
+  const setSelected = (id: string | null) => { setInnerSel(id); onSelectRun?.(id); };
   const [form, setForm] = useState<{ agent_id: string; title: string; goal: string } | null>(null);
   const [confirmStart, setConfirmStart] = useState(false);
   const [cancelling, setCancelling] = useState<AgentRun | null>(null);
   const [approving, setApproving] = useState<Approval | null>(null);
   const [deciding, setDeciding] = useState<string | null>(null);
 
-  const runs = useG8Query((signal) => g8Get("/agent/runs", { statuses: status || undefined, agent_id: agentId, limit }, { signal }), [status, agentId, limit]);
+  const runs = useG8Query((signal) => g8Get("/agent/runs", { statuses: status || undefined, agent_id: agentId, limit }, { signal }), [status, agentId, limit, refreshKey]);
   const approvals = useG8Query((signal) => g8Get("/agent/approvals", undefined, { signal }), []);
   const specialists = useG8Query((signal) => g8Get("/agent/specialists", undefined, { signal }), [], { enabled: form != null });
   const detail = useJobPoll<AgentRun>((signal) => g8Get<AgentRun>(`/agent/runs/${selected}`, undefined, { signal }).then((r) => bodyOf<AgentRun>(r)), {
-    enabled: selected != null, isTerminal: isTerminalRun, intervalMs: pollMs, maxIntervalMs: pollMs * 4, onDone: () => void runs.refetch(),
+    enabled: selected != null && !hideDetail, isTerminal: isTerminalRun, intervalMs: pollMs, maxIntervalMs: pollMs * 4, onDone: () => void runs.refetch(),
   });
 
   // Switching runs keeps `enabled` true, so restart the poll explicitly.
-  useEffect(() => { if (selected) detail.start(); }, [selected]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { if (selected && !hideDetail) detail.start(); }, [selected]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // A run that stops on an approval keeps polling: refresh the approvals on every poll that lands.
-  useEffect(() => { if (selected && detail.attempts > 0) void approvals.refetch(); }, [detail.attempts]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { if (selected && !hideDetail && detail.attempts > 0) void approvals.refetch(); }, [detail.attempts]); // eslint-disable-line react-hooks/exhaustive-deps
 
   const start = useG8Mutation(() => g8Post<AgentRun>("/agent/runs", { agent_id: form?.agent_id ?? agentId, title: form?.title.trim(), goal: form?.goal.trim() }), {
     onSuccess: (res) => { setConfirmStart(false); setForm(null); setSelected(bodyOf<AgentRun>(res).work_item_id ?? null); void runs.refetch(); },
@@ -91,8 +100,8 @@ export function AgentRuns({ agentId, pageSize = 20, pollMs = 3000, className }:
   return (
     <div className={`flex flex-col gap-4 ${className ?? ""}`}>
       {pending.length > 0 ? (
-        <div className="rounded-md border border-amber-300 p-3" data-testid="approvals">
-          <h3 className="mb-2 text-sm font-semibold">Waiting for your decision ({pending.length})</h3>
+        <div className="rounded-md border border-warning-foreground/30 p-3" data-testid="approvals">
+          <h3 className="mb-2 text-sm font-medium">Waiting for your decision ({pending.length})</h3>
           <ul className="flex flex-col gap-2">
             {pending.map((a) => (
               <li key={a.id} className="flex flex-wrap items-center justify-between gap-2 text-sm">
@@ -147,11 +156,11 @@ export function AgentRuns({ agentId, pageSize = 20, pollMs = 3000, className }:
       {!runs.loading && !runs.error && rows.length === 0 ? <EmptyState title="No runs yet" description="A run is one goal worked on by an agent, step by step, with approvals where it matters." /> : null}
       {rows.length < total ? <Button variant="outline" size="sm" onClick={() => setLimit(limit + pageSize)}>Load more</Button> : null}
 
-      {selected ? (
+      {selected && !hideDetail ? (
         <div className="rounded-md border p-3" data-testid="run-detail">
           {current ? (
             <>
-              <div className="flex items-center justify-between"><h3 className="font-semibold">{current.title}</h3><span className="text-sm">{current.status}{detail.polling ? " (updating)" : ""}</span></div>
+              <div className="flex items-center justify-between"><h3 className="font-medium">{current.title}</h3><span className="text-sm">{current.status}{detail.polling ? " (updating)" : ""}</span></div>
               <dl className="mt-2 grid grid-cols-2 gap-1 text-sm">
                 <dt className="text-muted-foreground">Current step</dt><dd>{current.current_step ?? "-"}</dd>
                 <dt className="text-muted-foreground">Next action</dt><dd>{current.next_action ?? "-"}</dd>

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

@@ -10,7 +10,7 @@
  *   3. attachSkillsToAgent      POST   /voice/agents/{agent_id}/skills { action_ids } (write)
  *   4. detachSkillFromAgent     DELETE /voice/agents/{agent_id}/skills/{action_id}    (destructive, ConfirmSpendDialog)
  *   5. listModels               GET    /skills/models                                 (read)
- *   6. createSkill              POST   /skills { name, runtime_type: "llm", llm_config } (write)
+ *   6. createSkill              POST   /skills { name, runtime_type: "llm", llm_config: { model, prompt_template } } (write)
  *
  * Detaching never deletes the skill; it only stops this agent from using it.
  */
@@ -42,16 +42,16 @@ export function AgentSkillsPanel({ agentId, onChanged, className }: AgentSkillsP
   const [attachingId, setAttachingId] = useState<string | null>(null);
   useEffect(() => { setDetaching(null); setCreating(null); setAttachingId(null); }, [agentId]);
 
-  const attached = useG8Query((signal) => g8Get(`/voice/agents/${agentId}/skills`, undefined, { signal }), [agentId]);
+  const attached = useG8Query((signal) => g8Get(`/voice/agents/${encodeURIComponent(agentId)}/skills`, undefined, { signal }), [agentId]);
   const all = useG8Query((signal) => g8Get("/skills", undefined, { signal }), []);
   const models = useG8Query((signal) => g8Get("/skills/models", undefined, { signal }), [], { enabled: creating != null });
 
   const changed = () => { void attached.refetch(); void all.refetch(); onChanged?.(); };
-  const attach = useG8Mutation((actionId: string) => g8Post(`/voice/agents/${agentId}/skills`, { action_ids: [actionId] }), { onSuccess: changed });
+  const attach = useG8Mutation((actionId: string) => g8Post(`/voice/agents/${encodeURIComponent(agentId)}/skills`, { action_ids: [actionId] }), { onSuccess: changed });
   const attachOne = async (id: string) => { setAttachingId(id); await attach.mutate(id); setAttachingId(null); };
-  const detach = useG8Mutation((actionId: string) => g8Delete(`/voice/agents/${agentId}/skills/${actionId}`), { onSuccess: () => { setDetaching(null); changed(); } });
+  const detach = useG8Mutation((actionId: string) => g8Delete(`/voice/agents/${encodeURIComponent(agentId)}/skills/${encodeURIComponent(actionId)}`), { onSuccess: () => { setDetaching(null); changed(); } });
   const create = useG8Mutation(
-    (v: NonNullable<typeof creating>) => g8Post("/skills", { name: v.name, description: v.description || undefined, runtime_type: "llm", llm_config: { prompt: v.prompt, model: v.model } }),
+    (v: NonNullable<typeof creating>) => g8Post("/skills", { name: v.name, description: v.description || undefined, runtime_type: "llm", llm_config: { model: v.model, prompt_template: v.prompt } }),
     { onSuccess: () => { setCreating(null); changed(); } },
   );
 
@@ -63,7 +63,7 @@ export function AgentSkillsPanel({ agentId, onChanged, className }: AgentSkillsP
   return (
     <div className={`flex flex-col gap-5 ${className ?? ""}`}>
       <div className="flex flex-col gap-2">
-        <h3 className="text-sm font-semibold">Attached skills</h3>
+        <h3 className="text-sm font-medium">Attached skills</h3>
         {attached.error ? <ApiError error={attached.error} title="Could not load the agent's skills" onRetry={() => void attached.refetch()} /> : null}
         {attached.loading && mine.length === 0 ? <Skeleton className="h-10 w-full" /> : null}
         <ul className="divide-y rounded-md border">
@@ -79,7 +79,7 @@ export function AgentSkillsPanel({ agentId, onChanged, className }: AgentSkillsP
 
       <div className="flex flex-col gap-2">
         <div className="flex items-center justify-between">
-          <h3 className="text-sm font-semibold">Available skills</h3>
+          <h3 className="text-sm font-medium">Available skills</h3>
           <Button size="sm" variant="outline" onClick={() => setCreating({ name: "", description: "", prompt: "", model: "" })}>New skill</Button>
         </div>
         {all.error ? <ApiError error={all.error} title="Could not load skills" onRetry={() => void all.refetch()} /> : null}

package/blocks/agents/components/agent-test-history.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+/**
+ * AgentTestHistory: the saved test cases of one agent and every run of them. Cases can be renamed or re-worded (only the fields you
+ * change are sent) and deleted (destructive, confirmed); the run history shows when each case ran and whether it passed.
+ * Running a test stays in AgentTestConsole; both are free (dry runs).
+ *
+ * SDK operations, in order:
+ *   1. listAgentTestCases   GET    /voice/agents/{agent_id}/test-cases                          (read)
+ *   2. updateAgentTestCase  PUT    /voice/agents/{agent_id}/test-cases/{test_case_id}  { changed fields }   (write)
+ *   3. deleteAgentTestCase  DELETE /voice/agents/{agent_id}/test-cases/{test_case_id}          (destructive, ConfirmSpendDialog)
+ *   4. listAgentTestRuns    GET    /voice/agents/{agent_id}/test-runs?limit&test_case_id       (read)  "Load more" grows the limit
+ */
+import { useEffect, useState } from "react";
+import { Button, Input, Label, 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 { FormSheet } from "@/g8/components/screen/form-sheet";
+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 { g8Delete, g8Get, g8Put } from "@/g8/lib/g8-client";
+import { listOf } from "../lib/agent-types";
+import { LoadMore, useGrowingList } from "../lib/load-more";
+
+export interface AgentTestHistoryProps {
+  agentId: string;
+  className?: string;
+}
+
+interface Case { test_case_id?: string; id?: string; name: string; input_message?: string; channel?: string; assertion_type?: string; expected_output?: unknown }
+interface TestRun { id?: string; run_id?: string; test_case_id?: string; assertion_result?: string; created_at?: string; mode?: string }
+
+const caseId = (c: Case): string => c.test_case_id ?? c.id ?? "";
+const CHANNELS = ["chat", "inbound", "outbound"] as const;
+const ASSERTIONS = ["contains", "not_contains", "exact", "refuses", "expects_tool", "cites_collection", "llm_judge"] as const;
+/** Only these compare against a single text; the others keep their expected_output / config untouched (edit them in graph8). */
+const TEXT_TYPES: readonly string[] = ["contains", "not_contains", "exact"];
+const expectedText = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : JSON.stringify(v));
+
+/** Only the fields whose value differs from the loaded case. */
+export function changedFields(before: Case, draft: { name: string; input_message: string; channel: string; assertion_type: string; expected_output: string }): Record<string, string> {
+  const base = { name: before.name, input_message: before.input_message ?? "", channel: before.channel ?? "chat", assertion_type: before.assertion_type ?? "contains", expected_output: expectedText(before.expected_output) };
+  return Object.fromEntries(Object.entries(draft).filter(([k, v]) => v !== (base as Record<string, string>)[k] && !(k === "expected_output" && !TEXT_TYPES.includes(draft.assertion_type))));
+}
+
+function EditCase({ agentId, row, onClose, onSaved }: { agentId: string; row: Case | null; onClose: () => void; onSaved: () => void }) {
+  const [d, setD] = useState({ name: "", input_message: "", channel: "chat", assertion_type: "contains", expected_output: "" });
+  useEffect(() => { if (row) setD({ name: row.name, input_message: row.input_message ?? "", channel: row.channel ?? "chat", assertion_type: row.assertion_type ?? "contains", expected_output: expectedText(row.expected_output) }); }, [row]);
+  const diff = row ? changedFields(row, d) : {};
+  const save = useG8Mutation(() => g8Put(`/voice/agents/${encodeURIComponent(agentId)}/test-cases/${encodeURIComponent(caseId(row as Case))}`, diff), { onSuccess: () => { onSaved(); onClose(); } });
+  const needsText = TEXT_TYPES.includes(d.assertion_type);
+  const set = (patch: Partial<typeof d>) => setD((x) => ({ ...x, ...patch }));
+  return (
+    <FormSheet open={row != null} onOpenChange={(o) => !o && onClose()} title="Edit test case" description="Only the fields you change are saved."
+      footer={<><Button variant="ghost" onClick={onClose}>Cancel</Button><Button loading={save.loading} disabled={Object.keys(diff).length === 0 || !d.name.trim() || !d.input_message.trim() || (needsText && !d.expected_output.trim())} onClick={() => void save.mutate(undefined)}>Save changes</Button></>}>
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-col gap-1"><Label htmlFor="tc-name">Name</Label><Input id="tc-name" value={d.name} onChange={(e) => set({ name: e.target.value })} /></div>
+        <div className="flex flex-col gap-1"><Label htmlFor="tc-input">What the person says</Label><Textarea id="tc-input" rows={3} value={d.input_message} onChange={(e) => set({ input_message: e.target.value })} /></div>
+        <div className="grid grid-cols-2 gap-3">
+          <div className="flex flex-col gap-1"><Label htmlFor="tc-channel">Channel</Label>
+            <select id="tc-channel" className="h-9 rounded-md border bg-background px-2 text-sm" value={d.channel} onChange={(e) => set({ channel: e.target.value })}>{CHANNELS.map((c) => <option key={c} value={c}>{c}</option>)}</select></div>
+          <div className="flex flex-col gap-1"><Label htmlFor="tc-assertion">The agent</Label>
+            <select id="tc-assertion" className="h-9 rounded-md border bg-background px-2 text-sm" value={d.assertion_type} onChange={(e) => set({ assertion_type: e.target.value })}>{ASSERTIONS.map((c) => <option key={c} value={c}>{c.replace("_", " ")}</option>)}</select></div>
+        </div>
+        {needsText ? <div className="flex flex-col gap-1"><Label htmlFor="tc-expected">Text to check</Label><Input id="tc-expected" value={d.expected_output} onChange={(e) => set({ expected_output: e.target.value })} /></div> : null}
+        {save.error ? <ApiError error={save.error} title="Could not save the case" /> : null}
+      </div>
+    </FormSheet>
+  );
+}
+
+export function AgentTestHistory({ agentId, className }: AgentTestHistoryProps) {
+  const [editing, setEditing] = useState<Case | null>(null);
+  const [deleting, setDeleting] = useState<Case | null>(null);
+  const [only, setOnly] = useState("");
+  useEffect(() => { setEditing(null); setDeleting(null); setOnly(""); }, [agentId]);
+  const cases = useG8Query((signal) => g8Get(`/voice/agents/${encodeURIComponent(agentId)}/test-cases`, undefined, { signal }), [agentId]);
+  const runs = useGrowingList<TestRun>(async (limit, signal) => listOf<TestRun>(await g8Get(`/voice/agents/${encodeURIComponent(agentId)}/test-runs`, { limit, test_case_id: only || undefined }, { signal }), "items", "runs"), [agentId, only], { pageSize: 25, max: 200 });
+  const remove = useG8Mutation((id: string) => g8Delete(`/voice/agents/${encodeURIComponent(agentId)}/test-cases/${encodeURIComponent(id)}`), { onSuccess: (_r, id) => { setDeleting(null); if (only === id) setOnly(""); void cases.refetch(); runs.reload(); } });
+  const rows = listOf<Case>(cases.data, "items", "test_cases", "cases");
+  const nameOf = (id?: string) => rows.find((c) => caseId(c) === id)?.name ?? "Ad-hoc message";
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <SectionCard title="Saved test cases" description="Each case is a message plus what the agent must do." flush>
+        {cases.error ? <div className="p-3"><ApiError error={cases.error} title="Could not load the test cases" onRetry={() => void cases.refetch()} /></div> : null}
+        {cases.loading && !cases.data ? <Skeleton className="m-3 h-10" /> : null}
+        <ul className="divide-y">
+          {rows.map((c) => (
+            <li key={caseId(c)} data-testid={`case-${caseId(c)}`} className="flex flex-wrap items-center justify-between gap-2 px-4 py-2 text-sm">
+              <span><span className="font-medium">{c.name}</span><span className="block text-xs text-muted-foreground">{c.assertion_type ?? "contains"}: {expectedText(c.expected_output) || "no text"}</span></span>
+              <span className="flex gap-1"><Button size="sm" variant="ghost" onClick={() => setOnly(only === caseId(c) ? "" : caseId(c))}>{only === caseId(c) ? "All runs" : "Runs"}</Button><Button size="sm" variant="outline" onClick={() => setEditing(c)}>Edit</Button><Button size="sm" variant="ghost" onClick={() => setDeleting(c)}>Delete</Button></span>
+            </li>
+          ))}
+        </ul>
+        {!cases.loading && !cases.error && rows.length === 0 ? <EmptyState compact title="No saved cases" description="Save a dry run from the Test tab to keep it here." /> : null}
+      </SectionCard>
+      <SectionCard title="Run history" description={only ? `Runs of ${nameOf(only)}` : "Every test run, newest first"} flush>
+        {runs.error ? <div className="p-3"><ApiError error={runs.error} title="Could not load the run history" onRetry={runs.reload} /></div> : null}
+        {runs.loading ? <Skeleton className="m-3 h-10" /> : null}
+        <ul className="divide-y">
+          {runs.items.map((r, i) => (
+            <li key={r.id ?? r.run_id ?? i} className="flex items-center justify-between gap-2 px-4 py-2 text-sm">
+              <span>{nameOf(r.test_case_id)}</span>
+              <span className="flex items-center gap-2"><StatusPill tone={toneForStatus(r.assertion_result === "pass" ? "completed" : r.assertion_result === "fail" || r.assertion_result === "error" ? "failed" : "pending")} dot>{r.assertion_result ?? "not judged"}</StatusPill><span className="text-xs text-muted-foreground">{r.created_at ? new Date(r.created_at).toLocaleString() : ""}</span></span>
+            </li>
+          ))}
+        </ul>
+        {!runs.loading && !runs.error && runs.items.length === 0 ? <EmptyState compact title="No runs yet" description="Run a dry run or the whole sweep from the Test tab." /> : null}
+        <LoadMore list={runs} noun="runs" />
+      </SectionCard>
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the case" /> : null}
+      <EditCase agentId={agentId} row={editing} onClose={() => setEditing(null)} onSaved={() => { void cases.refetch(); }} />
+      <ConfirmSpendDialog open={deleting != null} tier="destructive" title={`Delete "${deleting?.name ?? "case"}"`} description="The case and its place in the regression sweep are removed. Past runs stay in the history." affected={1}
+        confirmLabel="Delete" confirming={remove.loading} onConfirm={() => deleting && void remove.mutate(caseId(deleting))} onCancel={() => setDeleting(null)} />
+    </div>
+  );
+}

package/blocks/agents/components/agents-screen.tsx

@@ -0,0 +1,226 @@
+"use client";
+
+/**
+ * AgentsScreen: the finished agents workspace. Two tabs.
+ *   Agents: stat strip (agents, active, inactive), search and status filter, the agent list, and for the open agent
+ *           (deep link ?id=) a detail panel with Configure (persona, voice, knowledge, skills, active switch, delete),
+ *           Test (free dry runs, saved cases, the activation gate, run a skill live) and Runs.
+ *   Runs:   every agent run in the workspace as a list; opening one (deep link ?run=) shows the full run (AgentRunDetail:
+ *           status, step, next action, credits, times, its approvals to approve or reject, cancel). Start a run from here.
+ * "New agent" opens a form sheet (name, role, what it is for, personality); the agent starts inactive and opens
+ * in the detail panel so voice, knowledge and skills can be added next.
+ *
+ * More tabs: Approvals (the inbox for everything agents ask permission for), Skill library (every skill, create/edit/delete),
+ * Company knowledge (the entries agents draw on: browse, search, author, verify, deprecate), Operators (autonomous
+ * monitors: on/off and the trust dial) and Assistant (sessions with the graph8 assistant). The open agent also has
+ * Conversations (its chat history and a message box), Activity (calls, skill runs, skill performance) and Test history
+ * (saved cases, edit/delete, every run). The header has From a template and Receptionist; an open agent can be
+ * duplicated or saved as a template.
+ *
+ * Composes: AgentBuilder (hideList), AgentTestConsole, AgentRuns, AgentApprovals, SkillLibrary, KnowledgeBrowser,
+ * AgentOperators, AssistantSessions, AgentConversations, AgentActivity, AgentTestHistory. Billable, external and
+ * destructive actions (document upload, run a skill, start/cancel a run, approve, send a chat message, turn an operator
+ * on, delete anything) stay inside those parts and are confirmed there with ConfirmSpendDialog.
+ *
+ * SDK operations of its own:
+ *   1. GET  /voice/agents?search&page_size=100   (voice.listAgents)       read
+ *   2. POST /voice/agents { role, persona, identity, entity_type, agent_status: "inactive" }  (voice.createAgent)  write
+ *   3. PUT  /voice/agents/{agent_id} { agent_status }   (voice.updateAgent)  write   activate / deactivate from the panel
+ * Slot props: renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions.
+ */
+import { useRef, useState, type ReactNode } from "react";
+import { Bot, Plus } from "lucide-react";
+import { Button, Input, Label, Skeleton, 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 { LoadMore } from "@/g8/components/paging-notices";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { DEFAULT_PERSONA, bodyOf, listOf } from "../lib/agent-types";
+import type { AgentSummary } from "../lib/agent-types";
+import { AgentActivity } from "./agent-activity";
+import { AgentApprovals } from "./agent-approvals";
+import { AgentBuilder } from "./agent-builder";
+import { AgentConversations } from "./agent-conversations";
+import { AgentOperators } from "./agent-operators";
+import { AgentRunDetail } from "./agent-run-detail";
+import { AgentRuns } from "./agent-runs";
+import { AgentTestConsole } from "./agent-test-console";
+import { AgentTestHistory } from "./agent-test-history";
+import { AssistantSessions } from "./assistant-sessions";
+import { DuplicateAgentButton } from "./duplicate-agent-button";
+import { FromTemplateButton } from "./from-template-button";
+import { KnowledgeBrowser } from "./knowledge-browser";
+import { ReceptionistButton } from "./receptionist-button";
+import { SaveAsTemplateButton } from "./save-as-template-button";
+import { SkillLibrary } from "./skill-library";
+
+export interface AgentsScreenProps {
+  /** Row-level extra actions (for example "Use in a campaign"). */
+  renderRowActions?: (agent: AgentSummary) => ReactNode;
+  renderDetailActions?: (agent: AgentSummary) => ReactNode;
+  extraDetailTabs?: Array<{ id: string; label: string; render: (agent: AgentSummary) => ReactNode }>;
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+const SCREEN_TABS = [
+  { id: "agents", label: "Agents" }, { id: "runs", label: "Runs" }, { id: "approvals", label: "Approvals" }, { id: "skills", label: "Skill library" },
+  { id: "knowledge", label: "Company knowledge" }, { id: "operators", label: "Operators" }, { id: "assistant", label: "Assistant" },
+];
+const TAB_IDS = SCREEN_TABS.map((t) => t.id);
+const FILTERS = [{ id: "", label: "All" }, { id: "active", label: "Active" }, { id: "inactive", label: "Inactive" }];
+
+interface NewAgent { name: string; role: string; description: string; persona: string }
+const blank = (): NewAgent => ({ name: "", role: "SDR", description: "", persona: "" });
+const tone = (status: string) => (status === "active" ? "positive" : status === "archived" ? "neutral" : "warning");
+
+/** Create sheet. Keeps the id of an agent it already created so a retry after a later failure never makes a twin. */
+function NewAgentSheet({ open, onOpenChange, onCreated }: { open: boolean; onOpenChange: (o: boolean) => void; onCreated: (id: string) => void }) {
+  const [form, setForm] = useState<NewAgent>(blank());
+  const created = useRef<string | null>(null);
+  const create = useG8Mutation(async () => {
+    if (created.current) return created.current;
+    const res = await g8Post("/voice/agents", {
+      entity_type: "agent", role: form.role.trim(), agent_status: "inactive", use_company_knowledge: true, identity: {},
+      persona: { ...DEFAULT_PERSONA, agent_name: form.name.trim(), description: form.description.trim(), persona: form.persona.trim() },
+    });
+    const id = bodyOf<{ agent?: { agent_id?: string } }>(res).agent?.agent_id ?? "";
+    created.current = id || null;
+    return id;
+  }, { onSuccess: (id) => { created.current = null; setForm(blank()); onOpenChange(false); if (id) onCreated(id); } });
+  const set = (patch: Partial<NewAgent>) => setForm((f) => ({ ...f, ...patch }));
+  const valid = Boolean(form.name.trim() && form.role.trim() && form.description.trim() && form.persona.trim());
+  return (
+    <FormSheet open={open} onOpenChange={onOpenChange} title="New agent" description="It starts inactive. Add a voice, knowledge and skills, test it, then turn it on."
+      footer={<><Button variant="ghost" onClick={() => onOpenChange(false)}>Cancel</Button><Button loading={create.loading} disabled={!valid} onClick={() => void create.mutate(undefined)}>Create agent</Button></>}>
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-col gap-1"><Label htmlFor="na-name">Name</Label><Input id="na-name" value={form.name} onChange={(e) => set({ name: e.target.value })} /></div>
+        <div className="flex flex-col gap-1"><Label htmlFor="na-role">Role</Label><Input id="na-role" value={form.role} onChange={(e) => set({ role: e.target.value })} /></div>
+        <div className="flex flex-col gap-1"><Label htmlFor="na-desc">What it is for</Label><Input id="na-desc" value={form.description} onChange={(e) => set({ description: e.target.value })} /></div>
+        <div className="flex flex-col gap-1"><Label htmlFor="na-persona">Personality and behaviour</Label><Textarea id="na-persona" rows={5} value={form.persona} onChange={(e) => set({ persona: e.target.value })} /></div>
+        {create.error ? <ApiError error={create.error} title="Could not create the agent" /> : null}
+      </div>
+    </FormSheet>
+  );
+}
+
+function AgentRow({ agent, selected, onOpen, extra }: { agent: AgentSummary; selected: boolean; onOpen: () => void; extra?: ReactNode }) {
+  return (
+    <li className={`flex items-center gap-3 border-b px-3 py-2 ${selected ? "bg-accent" : ""}`}>
+      <button type="button" data-testid={`agent-${agent.agent_id}`} onClick={onOpen} className="flex min-w-0 flex-1 items-center gap-3 text-left">
+        <EntityAvatar name={agent.agent_name} kind="person" size="md" />
+        <span className="min-w-0 flex-1">
+          <span className="block truncate text-sm font-medium">{agent.agent_name}</span>
+          <span className="block truncate text-xs text-muted-foreground">{agent.role}{agent.description ? ` - ${agent.description}` : ""}</span>
+        </span>
+        <StatusPill tone={tone(agent.agent_status)} dot>{agent.agent_status}</StatusPill>
+      </button>
+      {extra}
+    </li>
+  );
+}
+
+/** Agents per read; "Load more" appends the next page (the list used to stop silently at 100). */
+const AGENT_PAGE = 100;
+
+export function AgentsScreen({ renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, className }: AgentsScreenProps) {
+  const [tab, setTab] = useUrlState("tab", "agents");
+  const [selected, setSelected] = useUrlState("id", "");
+  const [search, setSearch] = useState("");
+  const [filter, setFilter] = useState("");
+  const [creating, setCreating] = useState(false);
+  const [run, setRun] = useUrlState("run", "");
+  const [view, setView] = useUrlState("view", "");
+  const closeAgent = () => { setSelected(""); setView(""); };
+  const closeRun = () => { setRun(""); setView(""); };
+  const expand = { expanded: view === "full", onExpandedChange: (e: boolean) => setView(e ? "full" : "") };
+  const [runsKey, setRunsKey] = useState(0);
+  const q = search.trim();
+
+  const agents = useLoadMoreList(byPage<AgentSummary>(AGENT_PAGE, async (page, signal) => {
+    const env = await g8Get("/voice/agents", { search: q || undefined, page, page_size: AGENT_PAGE }, { signal });
+    const rows = listOf<AgentSummary>(env, "agents");
+    return { rows, hasNext: hasNextOf(env, AGENT_PAGE, rows.length) };
+  }), [q]);
+  const all = agents.data ?? [];
+  const rows = filter ? all.filter((a) => a.agent_status === filter) : all;
+  // Resolve the open agent from the list first, else by id, so a search, a filter or a cold deep link never hides it.
+  const inList = all.find((a) => a.agent_id === selected);
+  const byId = useG8Query((signal) => g8Get(`/voice/agents/${encodeURIComponent(selected)}`, undefined, { signal }), [selected], { enabled: Boolean(selected) && !inList && !agents.loading });
+  const fetched = bodyOf<{ agent?: { agent_id: string; agent_status: string; role: string; persona?: { agent_name?: string; description?: string } } }>(byId.data).agent;
+  const open: AgentSummary | undefined = inList ?? (fetched ? { agent_id: fetched.agent_id, agent_name: fetched.persona?.agent_name ?? "Agent", role: fetched.role, agent_status: fetched.agent_status, description: fetched.persona?.description } : undefined);
+  const active = all.filter((a) => a.agent_status === "active").length;
+
+  const toggle = useG8Mutation((a: AgentSummary) => g8Put(`/voice/agents/${encodeURIComponent(a.agent_id)}`, { agent_status: a.agent_status === "active" ? "inactive" : "active" }), { onSuccess: () => { void agents.refetch(); void byId.refetch(); } });
+  const current = TAB_IDS.includes(tab) ? tab : "agents";
+  const openRun = (id: string) => { setRun(id); setTab("runs"); };
+
+  const detail = open ? (
+    <DetailPanel title={open.agent_name} subtitle={open.role} avatar={<EntityAvatar name={open.agent_name} kind="person" size="lg" />}
+      badges={<StatusPill tone={tone(open.agent_status)} dot>{open.agent_status}</StatusPill>} onClose={closeAgent} onExpand={() => setView("full")}
+      actions={<>
+        <Button size="sm" variant="outline" loading={toggle.loading} onClick={() => void toggle.mutate(open)}>{open.agent_status === "active" ? "Deactivate" : "Activate"}</Button>
+        <DuplicateAgentButton agent={open} onDuplicated={(id) => { void agents.refetch(); setSelected(id); }} />
+        <SaveAsTemplateButton agent={open} />
+        {renderDetailActions?.(open)}
+      </>}
+      tabs={[
+        { id: "configure", label: "Configure", content: <AgentBuilder key={`${open.agent_id}:${open.agent_status}`} hideList agentId={open.agent_id} onSelect={(id) => setSelected(id ?? "")} onChanged={() => void agents.refetch()} /> },
+        { id: "test", label: "Test", content: <AgentTestConsole agentId={open.agent_id} /> },
+        { id: "runs", label: "Runs", content: <AgentRuns agentId={open.agent_id} /> },
+        { id: "conversations", label: "Conversations", content: <AgentConversations agentId={open.agent_id} /> },
+        { id: "activity", label: "Activity", content: <AgentActivity agentId={open.agent_id} /> },
+        { id: "test-history", label: "Test history", content: <AgentTestHistory agentId={open.agent_id} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(open) })),
+      ]}>
+      {toggle.error ? <ApiError error={toggle.error} title="Could not change the status" /> : null}
+    </DetailPanel>
+  ) : selected && !agents.loading && !byId.loading && (byId.error || byId.data) ? <EmptyState title="Agent not found" description="It may have been deleted." /> : selected ? <Skeleton className="m-4 h-40" aria-label="Loading agent" /> : null;
+
+  const list = (
+    <div className="flex flex-col gap-3">
+      <Toolbar search={{ value: search, onChange: setSearch, placeholder: "Search agents" }} actions={toolbarActions}
+        filters={<div role="group" aria-label="Status" className="flex gap-1">{FILTERS.map((f) => <Button key={f.id || "all"} size="sm" variant={filter === f.id ? "default" : "outline"} onClick={() => setFilter(f.id)}>{f.label}</Button>)}</div>} />
+      {agents.error ? <ApiError error={agents.error} title="Could not load agents" onRetry={() => void agents.refetch()} /> : null}
+      {agents.loading && all.length === 0 ? <div className="space-y-2">{[0, 1, 2, 3].map((i) => <Skeleton key={i} className="h-14 w-full" />)}</div> : null}
+      <ul className="rounded-md border">
+        {rows.map((a) => <AgentRow key={a.agent_id} agent={a} selected={a.agent_id === selected} onOpen={() => setSelected(a.agent_id)} extra={renderRowActions?.(a)} />)}
+      </ul>
+      <LoadMore shown={all.length} noun="agents" hasMore={agents.hasMore} loading={agents.loadingMore} onLoadMore={agents.loadMore} />
+      {!agents.loading && !agents.error && rows.length === 0 ? (
+        <EmptyState title={all.length ? "No agents match" : "No agents yet"} description="An agent has a persona, a voice, knowledge and skills."
+          action={all.length ? undefined : <Button onClick={() => setCreating(true)}>New agent</Button>} />
+      ) : null}
+    </div>
+  );
+
+  return (
+    <ScreenLayout className={className} title="Agents" description="Build AI agents, prove they work before they talk to anyone, and follow the work they do."
+      icon={<Bot className="size-5" />} tabs={SCREEN_TABS} activeTab={current} onTabChange={setTab}
+      actions={<><FromTemplateButton onCreated={(id) => { void agents.refetch(); setSelected(id); setTab("agents"); }} /><ReceptionistButton /><Button onClick={() => setCreating(true)}><Plus className="mr-1 size-4" />New agent</Button></>}
+      stats={current === "agents" ? [
+        { label: "Agents", value: agents.hasMore ? `${all.length}+` : String(all.length) },
+        { label: "Active", value: String(active), tone: "positive" },
+        { label: "Inactive", value: String(all.filter((a) => a.agent_status === "inactive").length), tone: "warning" },
+      ] : undefined}>
+      {current === "approvals" ? <AgentApprovals onOpenRun={openRun} /> : current === "skills" ? <SkillLibrary /> : current === "knowledge" ? <KnowledgeBrowser />
+        : current === "operators" ? <AgentOperators /> : current === "assistant" ? <AssistantSessions onOpenRun={openRun} /> : current === "runs" ? (
+        <SplitView list={<AgentRuns hideDetail selectedId={run || null} onSelectRun={(id) => setRun(id ?? "")} refreshKey={runsKey} />} detailOpen={Boolean(run)} onCloseDetail={closeRun} {...expand} detailWidth="lg"
+          detail={run ? <DetailPanel title="Run" subtitle={run} onClose={closeRun} onExpand={() => setView("full")} tabs={[{ id: "run", label: "Run", content: <AgentRunDetail key={run} runId={run} onChanged={() => setRunsKey((k) => k + 1)} /> }]} /> : null} />
+      ) : <SplitView list={list} detail={detail} detailOpen={Boolean(selected)} onCloseDetail={closeAgent} {...expand} detailWidth="xl" />}
+      <NewAgentSheet open={creating} onOpenChange={setCreating} onCreated={(id) => { setSelected(id); setTab("agents"); void agents.refetch(); }} />
+    </ScreenLayout>
+  );
+}