@graph8/sdk 0.308.1 → 0.357.0

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

@@ -0,0 +1,199 @@
+"use client";
+
+/**
+ * AgentBuilder: list, create, edit and delete AI agents (voice and chat). Left column is the agent list;
+ * the editor has four sections: Persona (name, role, how it talks), Voice (voice, instructions per call
+ * type), Knowledge (AgentKnowledgePanel) and Skills (AgentSkillsPanel).
+ *
+ * SDK operations, in order:
+ *   1. listVoiceAgents       GET    /voice/agents?search&page&page_size           (read)
+ *   2. getVoiceAgent         GET    /voice/agents/{agent_id}                      (read)
+ *   3. listPresetVoices      GET    /voice/voice-library/presets                  (read)
+ *   4. createVoiceAgent      POST   /voice/agents  { role, persona, identity }    (write)
+ *   5. updateVoiceAgent      PUT    /voice/agents/{agent_id}                      (write)
+ *      persona / identity / knowledge are replaced whole: always send the full sub-object.
+ *   6. deleteVoiceAgent      DELETE /voice/agents/{agent_id}                      (destructive, ConfirmSpendDialog)
+ *
+ * Saving a draft never places a call or sends a message; activating (`agent_status: "active"`) is just a
+ * write, but the agent can then be picked by dialer sessions, so the toggle is explicit.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input, Label, Skeleton, Switch, 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 { DEFAULT_PERSONA, bodyOf, listOf, percent } from "../lib/agent-types";
+import type { AgentDetail, AgentSummary } from "../lib/agent-types";
+import { AgentKnowledgePanel } from "./agent-knowledge-panel";
+import { AgentSkillsPanel } from "./agent-skills-panel";
+
+export interface AgentBuilderProps {
+  /** Controlled selection. Without it the builder keeps its own. */
+  agentId?: string | null;
+  onSelect?: (agentId: string | null) => void;
+  /** Called after a create, update or delete so the host can refresh its own lists. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+type Section = "persona" | "voice" | "knowledge" | "skills";
+const SECTIONS: Array<{ id: Section; label: string }> = [
+  { id: "persona", label: "Persona" },
+  { id: "voice", label: "Voice" },
+  { id: "knowledge", label: "Knowledge" },
+  { id: "skills", label: "Skills" },
+];
+
+const blankDraft = (): AgentDetail => ({ agent_id: "", agent_status: "inactive", role: "SDR", persona: { ...DEFAULT_PERSONA }, identity: {}, use_company_knowledge: true });
+
+function Dial({ label, value, onChange, low, high }: { label: string; value: number; onChange: (v: number) => void; low: string; high: string }) {
+  return (
+    <div className="flex flex-col gap-1">
+      <Label>{label}: {percent(value)}</Label>
+      <input type="range" aria-label={label} min={0} max={1} step={0.05} value={value} onChange={(e) => onChange(Number(e.target.value))} />
+      <div className="flex justify-between text-xs text-muted-foreground"><span>{low}</span><span>{high}</span></div>
+    </div>
+  );
+}
+
+export function AgentBuilder({ agentId: controlled, onSelect, onChanged, className }: AgentBuilderProps) {
+  const [inner, setInner] = useState<string | null>(null);
+  const selected = controlled !== undefined ? controlled : inner;
+  const [creating, setCreating] = useState(false);
+  const [search, setSearch] = useState("");
+  const [section, setSection] = useState<Section>("persona");
+  const [draft, setDraft] = useState<AgentDetail | null>(null);
+  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 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 }), []);
+
+  useEffect(() => {
+    const agent = bodyOf<{ agent?: AgentDetail | null }>(detail.data).agent;
+    if (agent && !creating) setDraft({ ...agent, persona: { ...DEFAULT_PERSONA, ...agent.persona }, identity: agent.identity ?? {} });
+  }, [detail.data, creating]);
+
+  const save = useG8Mutation(
+    (d: AgentDetail) => {
+      const body = { role: d.role, persona: d.persona, identity: d.identity, use_company_knowledge: d.use_company_knowledge, agent_status: d.agent_status };
+      return d.agent_id ? g8Put(`/voice/agents/${d.agent_id}`, body) : g8Post("/voice/agents", { ...body, entity_type: "agent" });
+    },
+    {
+      onSuccess: (res) => {
+        const id = bodyOf<{ agent?: { agent_id?: string } }>(res).agent?.agent_id;
+        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();
+        onChanged?.();
+      },
+    },
+  );
+  const remove = useG8Mutation((id: string) => g8Delete(`/voice/agents/${id}`), {
+    onSuccess: () => { setDeleting(false); setDraft(null); choose(null); void agents.refetch(); onChanged?.(); },
+  });
+
+  const rows = listOf<AgentSummary>(agents.data, "agents");
+  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 } });
+  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="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>
+        </div>
+        {agents.error ? <ApiError error={agents.error} title="Could not load agents" onRetry={() => void agents.refetch()} /> : null}
+        {agents.loading && rows.length === 0 ? Array.from({ length: 4 }, (_, i) => <Skeleton key={i} className="h-12 w-full" />) : null}
+        <ul className="flex flex-col gap-1">
+          {rows.map((a) => (
+            <li key={a.agent_id}>
+              <button type="button" data-testid={`agent-${a.agent_id}`} onClick={() => choose(a.agent_id)}
+                className={`w-full rounded-md border p-2 text-left text-sm ${selected === a.agent_id && !creating ? "border-primary bg-accent" : ""}`}>
+                <span className="font-medium">{a.agent_name}</span>
+                <span className="block text-xs text-muted-foreground">{a.role} - {a.agent_status}</span>
+              </button>
+            </li>
+          ))}
+        </ul>
+        {!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>
+
+      <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 ? (
+          <>
+            <div role="tablist" className="flex gap-1 border-b">
+              {SECTIONS.map((s) => (
+                <button key={s.id} role="tab" type="button" aria-selected={section === s.id} disabled={!draft.agent_id && (s.id === "knowledge" || s.id === "skills")}
+                  className={`px-3 py-2 text-sm disabled:opacity-40 ${section === s.id ? "border-b-2 border-primary font-medium" : "text-muted-foreground"}`} onClick={() => setSection(s.id)}>{s.label}</button>
+              ))}
+            </div>
+
+            {section === "persona" ? (
+              <div className="flex flex-col gap-3">
+                <div className="grid gap-3 sm:grid-cols-2">
+                  <div className="flex flex-col gap-1"><Label htmlFor="agent-name">Name</Label><Input id="agent-name" value={draft.persona.agent_name} onChange={(e) => setPersona({ agent_name: e.target.value })} /></div>
+                  <div className="flex flex-col gap-1"><Label htmlFor="agent-role">Role</Label><Input id="agent-role" value={draft.role} onChange={(e) => setDraft({ ...draft, role: e.target.value })} /></div>
+                </div>
+                <div className="flex flex-col gap-1"><Label htmlFor="agent-desc">What it is for</Label><Input id="agent-desc" value={draft.persona.description} onChange={(e) => setPersona({ description: e.target.value })} /></div>
+                <div className="flex flex-col gap-1"><Label htmlFor="agent-persona">Personality and behaviour</Label><Textarea id="agent-persona" rows={5} value={draft.persona.persona} onChange={(e) => setPersona({ persona: e.target.value })} /></div>
+                <div className="grid gap-3 sm:grid-cols-3">
+                  <Dial label="Formality" low="Casual" high="Formal" value={draft.persona.formality_level} onChange={(v) => setPersona({ formality_level: v })} />
+                  <Dial label="Conciseness" low="Detailed" high="Brief" value={draft.persona.conciseness_level} onChange={(v) => setPersona({ conciseness_level: v })} />
+                  <Dial label="Assertiveness" low="Gentle" high="Direct" value={draft.persona.assertiveness_level} onChange={(v) => setPersona({ assertiveness_level: v })} />
+                </div>
+              </div>
+            ) : null}
+
+            {section === "voice" ? (
+              <div className="flex flex-col gap-3">
+                <div className="flex flex-col gap-1">
+                  <Label htmlFor="agent-voice">Voice</Label>
+                  <select id="agent-voice" className="h-9 rounded-md border bg-background px-2 text-sm" value={draft.identity.voice ?? ""} onChange={(e) => setDraft({ ...draft, identity: { ...draft.identity, voice: e.target.value || null } })}>
+                    <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>
+                </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>
+                <div className="flex flex-col gap-1"><Label htmlFor="agent-voicemail">Voicemail message</Label><Textarea id="agent-voicemail" rows={2} value={draft.persona.outbound_voicemail_prompt ?? ""} onChange={(e) => setPersona({ outbound_voicemail_prompt: e.target.value || null })} /></div>
+              </div>
+            ) : null}
+
+            {section === "knowledge" && draft.agent_id ? (
+              <AgentKnowledgePanel key={draft.agent_id} agentId={draft.agent_id} useCompanyKnowledge={draft.use_company_knowledge} onToggleCompanyKnowledge={(v) => setDraft({ ...draft, use_company_knowledge: v })} />
+            ) : null}
+            {section === "skills" && draft.agent_id ? <AgentSkillsPanel key={draft.agent_id} agentId={draft.agent_id} /> : null}
+
+            {section === "persona" || section === "voice" ? (
+              <div className="flex flex-wrap items-center gap-3 border-t pt-3">
+                <label className="flex items-center gap-2 text-sm"><Switch checked={draft.agent_status === "active"} aria-label="Active" onCheckedChange={(on) => setDraft({ ...draft, agent_status: on ? "active" : "inactive" })} />Active (can be used for calls and chats)</label>
+                {save.error ? <ApiError error={save.error} title="Could not save the agent" /> : null}
+                <div className="ml-auto flex gap-2">
+                  {draft.agent_id ? <Button variant="ghost" onClick={() => setDeleting(true)}>Delete</Button> : null}
+                  <Button loading={save.loading} disabled={!valid} onClick={() => void save.mutate(draft)}>{draft.agent_id ? "Save changes" : "Create agent"}</Button>
+                </div>
+              </div>
+            ) : null}
+          </>
+        ) : null}
+      </section>
+
+      <ConfirmSpendDialog open={deleting} tier="destructive" title={`Delete agent "${draft?.persona.agent_name ?? ""}"`} description="Its settings, attached skills and uploaded documents are removed. Past calls stay in the call log."
+        affected={1} confirming={remove.loading} onConfirm={() => draft?.agent_id && void remove.mutate(draft.agent_id)} onCancel={() => setDeleting(false)} />
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the agent" /> : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,144 @@
+"use client";
+
+/**
+ * AgentKnowledgePanel: what an agent knows. Two sources: the agent's own documents (PDF, DOCX or text,
+ * embedded into a private vector store) and the organisation's shared knowledge (read-only here), which
+ * the agent uses when "Use company knowledge" is on.
+ *
+ * SDK operations, in order:
+ *   1. updateVoiceAgent       PUT    /voice/agents/{agent_id} { use_company_knowledge }        (write)
+ *   2. listAgentDocuments     GET    /voice/agents/{agent_id}/documents                         (read)
+ *   3. uploadAgentDocuments   POST   /voice/agents/{agent_id}/documents/upload (multipart)      (billable, ConfirmSpendDialog)
+ *   4. deleteAgentDocument    DELETE /voice/agent-documents/{document_id}                       (destructive, ConfirmSpendDialog)
+ *   5. searchKnowledge        GET    /knowledge/search?query&limit                              (read)
+ *
+ * Uploading extracts and embeds text with a paid model: the dialog states the file count and a rough
+ * credit estimate before anything is sent. 5 MiB maximum per upload through the proxy (the API itself allows 25 MB per file).
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { Button, Input, Skeleton, Switch } 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 { listOf } from "../lib/agent-types";
+
+export interface AgentKnowledgePanelProps {
+  agentId: string;
+  useCompanyKnowledge: boolean;
+  /** Called after the toggle was saved to the agent. */
+  onToggleCompanyKnowledge?: (value: boolean) => void;
+  /** Rough credits per file shown in the upload confirmation. Default 5. */
+  creditsPerFile?: number;
+  className?: string;
+}
+
+interface DocRow { document_id?: string; id?: string; filename?: string; name?: string; status?: string; chunk_count?: number }
+interface KnowledgeHit { id?: string; concept_id?: string; title?: string; summary?: string; snippet?: string; concept_type?: string }
+
+/** The app's /api/g8 proxy caps a request body at 5 MiB, so that (not the 25 MB the API allows) is the real limit per upload. */
+const MAX_BYTES = 5 * 1024 * 1024 - 64 * 1024; // headroom for multipart boundaries and headers
+
+export function AgentKnowledgePanel({ agentId, useCompanyKnowledge, onToggleCompanyKnowledge, creditsPerFile = 5, className }: AgentKnowledgePanelProps) {
+  const fileInput = useRef<HTMLInputElement>(null);
+  const [pending, setPending] = useState<File[] | null>(null);
+  const [tooBig, setTooBig] = useState<string | null>(null);
+  const [removing, setRemoving] = useState<DocRow | null>(null);
+  const [query, setQuery] = useState("");
+  const [submitted, setSubmitted] = useState("");
+
+  // Everything below is tied to one agent: drop pending dialogs and search state when it changes.
+  useEffect(() => { setPending(null); setRemoving(null); setTooBig(null); setQuery(""); setSubmitted(""); }, [agentId]);
+
+  const docs = useG8Query((signal) => g8Get(`/voice/agents/${agentId}/documents`, undefined, { signal }), [agentId]);
+  const hits = useG8Query((signal) => g8Get("/knowledge/search", { query: submitted, limit: 8 }, { signal }), [submitted], { enabled: submitted.length > 0 });
+
+  const toggle = useG8Mutation((v: boolean) => g8Put(`/voice/agents/${agentId}`, { use_company_knowledge: v }), { onSuccess: (_r, v) => onToggleCompanyKnowledge?.(v) });
+  const upload = useG8Mutation(
+    (files: File[]) => {
+      const form = new FormData();
+      for (const f of files) form.append("files", f);
+      return g8Post(`/voice/agents/${agentId}/documents/upload`, form);
+    },
+    { onSuccess: () => { setPending(null); void docs.refetch(); } },
+  );
+  const remove = useG8Mutation((id: string) => g8Delete(`/voice/agent-documents/${id}`), { onSuccess: () => { setRemoving(null); void docs.refetch(); } });
+
+  const rows = listOf<DocRow>(docs.data, "documents", "items", "files");
+  const hitRows = listOf<KnowledgeHit>(hits.data, "items");
+
+  const onPick = (list: FileList | null) => {
+    const files = Array.from(list ?? []);
+    const total = files.reduce((n, f) => n + f.size, 0);
+    const big = files.find((f) => f.size > MAX_BYTES);
+    setTooBig(big ? `${big.name} is over 5 MB.` : total > MAX_BYTES ? "Those files add up to more than 5 MB; upload them in smaller batches." : null);
+    if (files.length && !big && total <= MAX_BYTES) setPending(files);
+    if (fileInput.current) fileInput.current.value = "";
+  };
+
+  return (
+    <div className={`flex flex-col gap-5 ${className ?? ""}`}>
+      <label className="flex items-center gap-2 text-sm">
+        <Switch aria-label="Use company knowledge" checked={useCompanyKnowledge} disabled={toggle.loading} onCheckedChange={(v) => void toggle.mutate(v)} />
+        Use company knowledge (what your organisation has written down) in answers
+      </label>
+      {toggle.error ? <ApiError error={toggle.error} title="Could not change the setting" /> : null}
+
+      <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>
+          <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>
+        {tooBig ? <p role="alert" className="text-sm text-destructive">{tooBig}</p> : null}
+        {docs.error ? <ApiError error={docs.error} title="Could not load documents" onRetry={() => void docs.refetch()} /> : null}
+        {docs.loading && rows.length === 0 ? <Skeleton className="h-10 w-full" /> : null}
+        <ul className="divide-y rounded-md border">
+          {rows.map((d) => {
+            const id = d.document_id ?? d.id ?? "";
+            return (
+              <li key={id} data-testid={`doc-${id}`} className="flex items-center justify-between gap-3 p-2 text-sm">
+                <span className="truncate">{d.filename ?? d.name ?? id}</span>
+                <span className="text-xs text-muted-foreground">{d.status ?? ""}{d.chunk_count != null ? ` - ${d.chunk_count} chunks` : ""}</span>
+                <Button size="sm" variant="ghost" onClick={() => setRemoving(d)}>Remove</Button>
+              </li>
+            );
+          })}
+        </ul>
+        {!docs.loading && !docs.error && rows.length === 0 ? <EmptyState title="No documents" description="Upload product sheets, scripts or FAQs the agent should answer from." /> : null}
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-sm font-semibold">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>
+        </form>
+        {hits.error ? <ApiError error={hits.error} title="Search failed" onRetry={() => void hits.refetch()} /> : null}
+        <ul className="flex flex-col gap-2">
+          {hitRows.map((h, i) => (
+            <li key={h.concept_id ?? h.id ?? i} className="rounded-md border p-2 text-sm">
+              <span className="font-medium">{h.title ?? h.concept_id ?? h.id}</span>
+              {h.concept_type ? <span className="ml-2 text-xs text-muted-foreground">{h.concept_type}</span> : null}
+              <p className="text-muted-foreground">{h.summary ?? h.snippet ?? ""}</p>
+            </li>
+          ))}
+        </ul>
+        {submitted && !hits.loading && !hits.error && hitRows.length === 0 ? <p className="text-sm text-muted-foreground">Nothing found for &quot;{submitted}&quot;.</p> : null}
+      </div>
+
+      {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"}`}
+        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)} />
+      <ConfirmSpendDialog open={removing != null} tier="destructive" title={`Remove "${removing?.filename ?? removing?.name ?? "document"}"`}
+        description="The agent stops using it straight away." affected={1} confirming={remove.loading}
+        onConfirm={() => removing && void remove.mutate(removing.document_id ?? removing.id ?? "")} onCancel={() => setRemoving(null)} />
+    </div>
+  );
+}

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

@@ -0,0 +1,175 @@
+"use client";
+
+/**
+ * AgentRuns: durable agent runs, live. Start a run (pick a specialist, give it a goal), watch its status
+ * and credits as it works (polled, the API has no streams), cancel it, and decide the approvals a run
+ * stops on before it acts.
+ *
+ * SDK operations, in order:
+ *   1. listAgentRuns        GET  /agent/runs?statuses&limit&offset            (read)
+ *   2. listAgentSpecialists GET  /agent/specialists                           (read)  the agent_id values a run accepts
+ *   3. createAgentRun       POST /agent/runs { agent_id, title, goal }        (write; spends credits as it runs, ConfirmSpendDialog)
+ *   4. getAgentRun          GET  /agent/runs/{run_id}                         (read)  polled until terminal
+ *   5. cancelAgentRun       POST /agent/runs/{run_id}/cancel                  (destructive, ConfirmSpendDialog)
+ *   6. listAgentApprovals   GET  /agent/approvals                             (read)
+ *   7. decideAgentApproval  POST /agent/approvals/{approval_id}/decide { decision }  (write; approving lets the run act, ConfirmSpendDialog)
+ *
+ * `workflow_started: false` on a create answer is normal (the worker picks the row up later); the run is
+ * saved either way and shows up in the list.
+ */
+
+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 { 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";
+
+export interface AgentRunsProps {
+  /** Only runs of this agent. */
+  agentId?: string;
+  pageSize?: number;
+  /** Poll interval for the selected run, in ms. Default 3000. */
+  pollMs?: number;
+  className?: string;
+}
+
+interface Approval { id: string; summary: string; risk_level: string; work_item_id: string; decision?: string | null; is_expired?: boolean }
+interface Specialist { agent_id?: string; id?: string; name?: string; title?: string; description?: string }
+
+const TERMINAL = new Set(["completed", "succeeded", "failed", "cancelled", "canceled"]);
+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) {
+  const [status, setStatus] = useState("");
+  const [limit, setLimit] = useState(pageSize);
+  const [selected, setSelected] = useState<string | null>(null);
+  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 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(),
+  });
+
+  // Switching runs keeps `enabled` true, so restart the poll explicitly.
+  useEffect(() => { if (selected) 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
+
+  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(); },
+    onError: () => setConfirmStart(false),
+  });
+  const cancel = useG8Mutation((id: string) => g8Post(`/agent/runs/${id}/cancel`, {}), { onSuccess: () => { setCancelling(null); void runs.refetch(); detail.start(); } });
+  const decide = useG8Mutation(async (v: { id: string; decision: "approve" | "reject" }) => {
+    setDeciding(v.id);
+    try { return await g8Post(`/agent/approvals/${v.id}/decide`, { decision: v.decision }); } finally { setDeciding(null); }
+  }, { onSuccess: () => { setApproving(null); void approvals.refetch(); void runs.refetch(); } });
+
+  const rows = listOf<AgentRun>(runs.data, "runs");
+  const total = bodyOf<{ total?: number }>(runs.data).total ?? rows.length;
+  // With an agentId the screen is about that agent's runs: only show approvals of runs it lists.
+  const shownRunIds = new Set(rows.map((r) => r.work_item_id));
+  const pending = listOf<Approval>(approvals.data).filter((a) => !a.decision && !a.is_expired && (!agentId || shownRunIds.has(a.work_item_id)));
+  const bench = listOf<Specialist>(specialists.data, "items");
+  const current = detail.status?.work_item_id === selected ? detail.status : undefined;
+  const formOk = Boolean(form?.title.trim() && form.goal.trim() && (form.agent_id || agentId));
+
+  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>
+          <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">
+                <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>
+              </li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+      {decide.error ? <ApiError error={decide.error} title="Could not record the decision" /> : null}
+
+      <div className="flex flex-wrap items-center gap-2">
+        <select aria-label="Status" className="h-9 rounded-md border bg-background px-2 text-sm" value={status} onChange={(e) => { setStatus(e.target.value); setLimit(pageSize); }}>
+          <option value="">All statuses</option>
+          {STATUSES.map((s) => <option key={s} value={s}>{s}</option>)}
+        </select>
+        <Button className="ml-auto" size="sm" onClick={() => setForm({ agent_id: agentId ?? "", title: "", goal: "" })}>Start a run</Button>
+      </div>
+
+      {form ? (
+        <div className="flex flex-col gap-3 rounded-md border p-3">
+          {!agentId ? (
+            <div className="flex flex-col gap-1"><Label htmlFor="run-agent">Specialist</Label>
+              <select id="run-agent" className="h-9 rounded-md border bg-background px-2 text-sm" value={form.agent_id} onChange={(e) => setForm({ ...form, agent_id: e.target.value })}>
+                <option value="">Choose a specialist</option>
+                {bench.map((s) => { const id = s.agent_id ?? s.id ?? ""; return <option key={id} value={id}>{s.name ?? s.title ?? id}</option>; })}
+              </select></div>
+          ) : null}
+          <div className="flex flex-col gap-1"><Label htmlFor="run-title">Title</Label><Input id="run-title" value={form.title} onChange={(e) => setForm({ ...form, title: e.target.value })} /></div>
+          <div className="flex flex-col gap-1"><Label htmlFor="run-goal">Goal</Label><Textarea id="run-goal" rows={3} value={form.goal} onChange={(e) => setForm({ ...form, goal: e.target.value })} /></div>
+          {start.error ? <ApiError error={start.error} title="Could not start the run" /> : null}
+          <div className="flex justify-end gap-2"><Button variant="ghost" onClick={() => setForm(null)}>Cancel</Button><Button disabled={!formOk} onClick={() => setConfirmStart(true)}>Start run</Button></div>
+        </div>
+      ) : null}
+
+      {runs.error ? <ApiError error={runs.error} title="Could not load runs" onRetry={() => void runs.refetch()} /> : null}
+      {runs.loading && rows.length === 0 ? Array.from({ length: 3 }, (_, i) => <Skeleton key={i} className="h-12 w-full" />) : null}
+      <ul className="divide-y rounded-md border">
+        {rows.map((r) => (
+          <li key={r.work_item_id}>
+            <button type="button" data-testid={`run-${r.work_item_id}`} onClick={() => setSelected(r.work_item_id)} className={`flex w-full items-center justify-between gap-3 p-2 text-left text-sm ${selected === r.work_item_id ? "bg-accent" : ""}`}>
+              <span className="font-medium">{r.title}</span>
+              <span className="text-xs text-muted-foreground">{r.status}{r.credits_spent ? ` - ${r.credits_spent} credits` : ""}</span>
+            </button>
+          </li>
+        ))}
+      </ul>
+      {!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 ? (
+        <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>
+              <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>
+                <dt className="text-muted-foreground">Credits</dt><dd>{current.credits_spent ?? 0}{current.credit_budget ? ` of ${current.credit_budget}` : ""}</dd>
+              </dl>
+              {!isTerminalRun(current) ? <Button className="mt-3" size="sm" variant="outline" onClick={() => setCancelling(current)}>Cancel run</Button> : null}
+            </>
+          ) : detail.error ? <ApiError error={detail.error} title="Could not load the run" onRetry={() => detail.start()} /> : <Skeleton className="h-16 w-full" />}
+          {cancel.error ? <ApiError error={cancel.error} title="Could not cancel the run" /> : null}
+        </div>
+      ) : null}
+
+      <ConfirmSpendDialog open={confirmStart} tier="billable" title={`Start "${form?.title ?? "run"}"`} description="The agent works toward the goal and spends credits as it goes. You can cancel at any time."
+        confirmLabel="Start run" confirming={start.loading} onConfirm={() => void start.mutate(undefined)} onCancel={() => setConfirmStart(false)} />
+      <ConfirmSpendDialog open={cancelling != null} tier="destructive" title={`Cancel "${cancelling?.title ?? "run"}"`} description="Work stops where it is. Steps already taken are not undone."
+        confirmLabel="Cancel run" confirming={cancel.loading} onConfirm={() => cancelling && void cancel.mutate(cancelling.work_item_id)} onCancel={() => setCancelling(null)} />
+      <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>
+  );
+}