@graph8/sdk 0.308.1 → 0.357.0

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

@@ -0,0 +1,126 @@
+"use client";
+
+/**
+ * AgentSkillsPanel: the skills (single-purpose actions, LLM or API) an agent can use. Attach and detach
+ * existing skills, or write a new LLM skill in place.
+ *
+ * SDK operations, in order:
+ *   1. listAgentSkills          GET    /voice/agents/{agent_id}/skills                (read)
+ *   2. listSkills               GET    /skills                                        (read)  org skills + system defaults
+ *   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)
+ *
+ * Detaching never deletes the skill; it only stops this agent from using it.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, 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 { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { listOf } from "../lib/agent-types";
+import type { SkillRow } from "../lib/agent-types";
+
+export interface AgentSkillsPanelProps {
+  agentId: string;
+  /** Called after an attach, detach or create. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+const idOf = (s: SkillRow): string => s.action_id ?? (s as unknown as { id?: string }).id ?? "";
+
+export function AgentSkillsPanel({ agentId, onChanged, className }: AgentSkillsPanelProps) {
+  const [detaching, setDetaching] = useState<SkillRow | null>(null);
+  const [creating, setCreating] = useState<{ name: string; description: string; prompt: string; model: string } | null>(null);
+
+  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 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 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 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 } }),
+    { onSuccess: () => { setCreating(null); changed(); } },
+  );
+
+  const mine = listOf<SkillRow>(attached.data, "actions", "skills", "items");
+  const attachedIds = new Set(mine.map(idOf));
+  const available = listOf<SkillRow>(all.data, "actions", "skills", "items").filter((s) => !attachedIds.has(idOf(s)));
+  const modelRows = listOf<{ id: string; label?: string }>(models.data, "models");
+
+  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>
+        {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">
+          {mine.map((s) => (
+            <li key={idOf(s)} data-testid={`attached-${idOf(s)}`} className="flex items-center justify-between gap-3 p-2 text-sm">
+              <span><span className="font-medium">{s.name}</span>{s.description ? <span className="block text-xs text-muted-foreground">{s.description}</span> : null}</span>
+              <Button size="sm" variant="ghost" onClick={() => setDetaching(s)}>Detach</Button>
+            </li>
+          ))}
+        </ul>
+        {!attached.loading && !attached.error && mine.length === 0 ? <EmptyState title="No skills attached" description="Attach a skill below so the agent can act, not only talk." /> : null}
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <div className="flex items-center justify-between">
+          <h3 className="text-sm font-semibold">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}
+        {attach.error ? <ApiError error={attach.error} title="Could not attach the skill" /> : null}
+        <ul className="divide-y rounded-md border">
+          {available.map((s) => (
+            <li key={idOf(s)} data-testid={`available-${idOf(s)}`} className="flex items-center justify-between gap-3 p-2 text-sm">
+              <span><span className="font-medium">{s.name}</span><span className="ml-2 text-xs text-muted-foreground">{s.runtime_type}</span>{s.description ? <span className="block text-xs text-muted-foreground">{s.description}</span> : null}</span>
+              <Button size="sm" variant="outline" loading={attachingId === idOf(s)} disabled={attachingId != null && attachingId !== idOf(s)} onClick={() => void attachOne(idOf(s))}>Attach</Button>
+            </li>
+          ))}
+        </ul>
+        {!all.loading && !all.error && available.length === 0 ? <p className="text-sm text-muted-foreground">Every skill is already attached.</p> : null}
+      </div>
+
+      <Dialog open={creating != null} onOpenChange={(o) => !o && setCreating(null)}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>New LLM skill</DialogTitle><DialogDescription>Use {"{variable}"} placeholders in the prompt for values the agent fills in.</DialogDescription></DialogHeader>
+          <div className="flex flex-col gap-3">
+            <div className="flex flex-col gap-1"><Label htmlFor="skill-name">Name</Label><Input id="skill-name" value={creating?.name ?? ""} onChange={(e) => setCreating((v) => v && { ...v, name: e.target.value })} /></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="skill-desc">What it does</Label><Input id="skill-desc" value={creating?.description ?? ""} onChange={(e) => setCreating((v) => v && { ...v, description: e.target.value })} /></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="skill-prompt">Prompt</Label><Textarea id="skill-prompt" rows={5} value={creating?.prompt ?? ""} onChange={(e) => setCreating((v) => v && { ...v, prompt: e.target.value })} /></div>
+            <div className="flex flex-col gap-1">
+              <Label htmlFor="skill-model">Model</Label>
+              <select id="skill-model" className="h-9 rounded-md border bg-background px-2 text-sm" value={creating?.model ?? ""} onChange={(e) => setCreating((v) => v && { ...v, model: e.target.value })}>
+                <option value="">Choose a model</option>
+                {modelRows.map((m) => <option key={m.id} value={m.id}>{m.label ?? m.id}</option>)}
+              </select>
+            </div>
+            {create.error ? <ApiError error={create.error} title="Could not create the skill" /> : null}
+          </div>
+          <DialogFooter>
+            <Button variant="ghost" onClick={() => setCreating(null)}>Cancel</Button>
+            <Button loading={create.loading} disabled={!creating?.name.trim() || !creating.prompt.trim() || !creating.model} onClick={() => creating && void create.mutate(creating)}>Create skill</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {detach.error ? <ApiError error={detach.error} title="Could not detach the skill" /> : null}
+      <ConfirmSpendDialog open={detaching != null} tier="destructive" title={`Detach "${detaching?.name ?? "skill"}"`} description="The agent can no longer use this skill. The skill itself is kept."
+        confirmLabel="Detach" confirming={detach.loading} onConfirm={() => detaching && void detach.mutate(idOf(detaching))} onCancel={() => setDetaching(null)} />
+    </div>
+  );
+}

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

@@ -0,0 +1,175 @@
+"use client";
+
+/**
+ * AgentTestConsole: check an agent before it talks to anyone. "Dry run" resolves what the agent WOULD
+ * receive (instructions, tools, grounding) for a message and judges an assertion, with no model call, no
+ * call placed and no message sent. "Run a skill" actually executes one attached skill with real input.
+ *
+ * SDK operations, in order:
+ *   1. listAgentTestCases       GET  /voice/agents/{agent_id}/test-cases                 (read)
+ *   2. getAgentTestSuiteStatus  GET  /voice/agents/{agent_id}/test-suite-status          (read)  the activation gate
+ *   3. runAgentTest             POST /voice/agents/{agent_id}/test { test_case_id | input_message, channel, ... }  (write, free)
+ *   4. createAgentTestCase      POST /voice/agents/{agent_id}/test-cases { name, input_message, assertion }       (write)
+ *   5. runAllAgentTests         POST /voice/agents/{agent_id}/test/run-all                (write, free)  regression sweep
+ *   6. listAgentSkills          GET  /voice/agents/{agent_id}/skills                      (read)
+ *   7. executeSkill             POST /skills/{action_id}/execute { input_data }           (external, ConfirmSpendDialog)
+ *
+ * A skill can call APIs, send messages or spend credits, so running one is confirmed first.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+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, pretty } from "../lib/agent-types";
+import type { SkillRow } from "../lib/agent-types";
+
+export interface AgentTestConsoleProps {
+  agentId: string;
+  className?: string;
+}
+
+interface CaseRow { test_case_id?: string; id?: string; name: string; input_message?: string; assertion_type?: string }
+type Channel = "chat" | "inbound" | "outbound";
+type Assertion = "contains" | "not_contains" | "exact" | "refuses";
+
+/**
+ * Verdict of a dry run. Voice answers `{ run: { assertion_result: "pass" | "fail" | "error", assertion_detail: { reason } } }`
+ * (`llm_judge` runs can be unmeasured or skipped: no verdict). true = pass, false = fail or error.
+ */
+export function verdictOf(body: unknown): boolean | undefined {
+  const run = ((body ?? {}) as { run?: Record<string, unknown> }).run ?? {};
+  const s = String(run.assertion_result ?? "").toLowerCase();
+  if (s === "pass") return true;
+  if (s === "fail" || s === "error") return false;
+  return undefined;
+}
+
+/** Why a run failed or errored, when voice says. */
+export function reasonOf(body: unknown): string | undefined {
+  const detail = (((body ?? {}) as { run?: { assertion_detail?: { reason?: unknown } } }).run?.assertion_detail ?? {}) as { reason?: unknown };
+  return typeof detail.reason === "string" ? detail.reason : undefined;
+}
+
+const NEEDS_TEXT: Record<string, boolean> = { contains: true, not_contains: true, exact: true, refuses: false };
+
+const idOf = (s: SkillRow): string => s.action_id ?? (s as unknown as { id?: string }).id ?? "";
+
+export function AgentTestConsole({ agentId, className }: AgentTestConsoleProps) {
+  const [mode, setMode] = useState<"dry" | "skill">("dry");
+  const [message, setMessage] = useState("");
+  const [channel, setChannel] = useState<Channel>("chat");
+  const [assertion, setAssertion] = useState<Assertion>("contains");
+  const [expected, setExpected] = useState("");
+  const [caseId, setCaseId] = useState("");
+  const [saveName, setSaveName] = useState("");
+  const [skillId, setSkillId] = useState("");
+  const [skillInput, setSkillInput] = useState("{}");
+  const [confirmRun, setConfirmRun] = useState(false);
+
+  // A different agent is a different test bench: clear inputs, results and any open confirmation.
+  useEffect(() => { setCaseId(""); setSkillId(""); setMessage(""); setExpected(""); setSaveName(""); setSkillInput("{}"); setConfirmRun(false); dry.reset(); sweep.reset(); live.reset(); }, [agentId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const cases = useG8Query((signal) => g8Get(`/voice/agents/${agentId}/test-cases`, undefined, { signal }), [agentId]);
+  const gate = useG8Query((signal) => g8Get(`/voice/agents/${agentId}/test-suite-status`, undefined, { signal }), [agentId]);
+  const skills = useG8Query((signal) => g8Get(`/voice/agents/${agentId}/skills`, undefined, { signal }), [agentId], { enabled: mode === "skill" });
+
+  // Always send the assertion type; only the types that compare against text carry (and require) it. "Must refuse" uses voice's default refusal markers.
+  const needsText = NEEDS_TEXT[assertion];
+  const assertionBody = { assertion_type: assertion, ...(needsText ? { expected_output: expected.trim() } : {}) };
+  const assertionReady = !needsText || expected.trim().length > 0;
+  const dry = useG8Mutation(() => g8Post(`/voice/agents/${agentId}/test`, caseId ? { test_case_id: caseId, mode: "dry_run" } : { input_message: message.trim(), channel, mode: "dry_run", ...assertionBody }));
+  const sweep = useG8Mutation(() => g8Post(`/voice/agents/${agentId}/test/run-all`, {}), { onSuccess: () => void gate.refetch() });
+  const save = useG8Mutation(() => g8Post(`/voice/agents/${agentId}/test-cases`, { name: saveName.trim(), input_message: message.trim(), channel, ...assertionBody }), {
+    onSuccess: () => { setSaveName(""); void cases.refetch(); void gate.refetch(); },
+  });
+  const live = useG8Mutation(() => g8Post(`/skills/${skillId}/execute`, { input_data: JSON.parse(skillInput || "{}") as Record<string, unknown> }), { onSuccess: () => setConfirmRun(false), onError: () => setConfirmRun(false) });
+
+  const caseRows = listOf<CaseRow>(cases.data, "items");
+  const skillRows = listOf<SkillRow>(skills.data, "actions", "skills", "items");
+  const gateBody = bodyOf<Record<string, unknown>>(gate.data);
+  const dryBody = bodyOf(dry.data);
+  const verdict = verdictOf(dryBody);
+  const inputOk = (() => { try { JSON.parse(skillInput || "{}"); return true; } catch { return false; } })();
+  const skillName = skillRows.find((s) => idOf(s) === skillId)?.name ?? "this skill";
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <div role="tablist" className="flex gap-1 border-b">
+        {([["dry", "Dry run"], ["skill", "Run a skill"]] as const).map(([id, label]) => (
+          <button key={id} role="tab" type="button" aria-selected={mode === id} onClick={() => setMode(id)}
+            className={`px-3 py-2 text-sm ${mode === id ? "border-b-2 border-primary font-medium" : "text-muted-foreground"}`}>{label}</button>
+        ))}
+      </div>
+      {gate.data !== undefined ? <p className="text-sm text-muted-foreground">Activation gate: {String(gateBody.activation_gate ?? gateBody.status ?? gateBody.gate ?? "see details")}</p> : null}
+
+      {mode === "dry" ? (
+        <div className="flex flex-col gap-3">
+          {cases.error ? <ApiError error={cases.error} title="Could not load saved cases" onRetry={() => void cases.refetch()} /> : null}
+          <div className="flex flex-col gap-1">
+            <Label htmlFor="test-case">Saved case</Label>
+            <select id="test-case" className="h-9 rounded-md border bg-background px-2 text-sm" value={caseId} onChange={(e) => setCaseId(e.target.value)}>
+              <option value="">Ad-hoc message</option>
+              {caseRows.map((c) => { const id = c.test_case_id ?? c.id ?? ""; return <option key={id} value={id}>{c.name}</option>; })}
+            </select>
+          </div>
+          {!caseId ? (
+            <>
+              <div className="flex flex-col gap-1"><Label htmlFor="test-message">What the person says</Label><Textarea id="test-message" rows={3} value={message} onChange={(e) => setMessage(e.target.value)} /></div>
+              <div className="grid gap-3 sm:grid-cols-3">
+                <div className="flex flex-col gap-1"><Label htmlFor="test-channel">Channel</Label>
+                  <select id="test-channel" className="h-9 rounded-md border bg-background px-2 text-sm" value={channel} onChange={(e) => setChannel(e.target.value as Channel)}><option value="chat">Chat</option><option value="inbound">Inbound call</option><option value="outbound">Outbound call</option></select></div>
+                <div className="flex flex-col gap-1"><Label htmlFor="test-assertion">The agent</Label>
+                  <select id="test-assertion" className="h-9 rounded-md border bg-background px-2 text-sm" value={assertion} onChange={(e) => setAssertion(e.target.value as Assertion)}><option value="contains">Must include</option><option value="not_contains">Must not include</option><option value="exact">Must equal</option><option value="refuses">Must refuse</option></select></div>
+                <div className="flex flex-col gap-1"><Label htmlFor="test-expected">Text to check</Label><Input id="test-expected" value={expected} onChange={(e) => setExpected(e.target.value)} /></div>
+              </div>
+            </>
+          ) : null}
+          <div className="flex flex-wrap gap-2">
+            <Button loading={dry.loading} disabled={caseId ? false : !message.trim() || !assertionReady} onClick={() => void dry.mutate(undefined)}>Run dry run</Button>
+            <Button variant="outline" loading={sweep.loading} onClick={() => void sweep.mutate(undefined)}>Run all saved cases</Button>
+            {!caseId && message.trim() ? (
+              <span className="ml-auto flex gap-2">
+                <Input aria-label="Case name" placeholder="Name this case" className="w-44" value={saveName} onChange={(e) => setSaveName(e.target.value)} />
+                <Button variant="outline" loading={save.loading} disabled={!saveName.trim() || !assertionReady} onClick={() => void save.mutate(undefined)}>Save case</Button>
+              </span>
+            ) : null}
+          </div>
+          {dry.error ? <ApiError error={dry.error} title="The dry run failed" /> : null}
+          {sweep.error ? <ApiError error={sweep.error} title="The regression run failed" /> : null}
+          {save.error ? <ApiError error={save.error} title="Could not save the case" /> : null}
+          {dry.data !== undefined ? (
+            <div data-testid="dry-result" className="rounded-md border p-3">
+              <p className="mb-2 text-sm font-medium">{verdict === undefined ? "Result" : verdict ? "Passed" : "Failed"}</p>
+              {reasonOf(dryBody) ? <p className="mb-2 text-sm">{reasonOf(dryBody)}</p> : null}
+              <pre className="max-h-80 overflow-auto text-xs">{pretty(dryBody)}</pre>
+            </div>
+          ) : null}
+          {sweep.data !== undefined ? <pre data-testid="sweep-result" className="max-h-60 overflow-auto rounded-md border p-3 text-xs">{pretty(bodyOf(sweep.data))}</pre> : null}
+        </div>
+      ) : (
+        <div className="flex flex-col gap-3">
+          {skills.error ? <ApiError error={skills.error} title="Could not load the agent's skills" onRetry={() => void skills.refetch()} /> : null}
+          <div className="flex flex-col gap-1">
+            <Label htmlFor="live-skill">Skill</Label>
+            <select id="live-skill" className="h-9 rounded-md border bg-background px-2 text-sm" value={skillId} onChange={(e) => setSkillId(e.target.value)}>
+              <option value="">Choose an attached skill</option>
+              {skillRows.map((s) => <option key={idOf(s)} value={idOf(s)}>{s.name}</option>)}
+            </select>
+          </div>
+          <div className="flex flex-col gap-1"><Label htmlFor="live-input">Input (JSON)</Label><Textarea id="live-input" rows={4} className="font-mono text-xs" value={skillInput} onChange={(e) => setSkillInput(e.target.value)} /></div>
+          {!inputOk ? <p role="alert" className="text-sm text-destructive">The input is not valid JSON.</p> : null}
+          <div><Button disabled={!skillId || !inputOk} onClick={() => setConfirmRun(true)}>Run skill</Button></div>
+          {live.error ? <ApiError error={live.error} title="The skill run failed" /> : null}
+          {live.data !== undefined ? <pre data-testid="live-result" className="max-h-80 overflow-auto rounded-md border p-3 text-xs">{pretty(bodyOf(live.data))}</pre> : null}
+        </div>
+      )}
+
+      <ConfirmSpendDialog open={confirmRun} tier="external" title={`Run ${skillName} now`} description="This really runs the skill. If it calls an API or messages someone, that happens for real and cannot be recalled."
+        confirmLabel="Run skill" confirming={live.loading} onConfirm={() => void live.mutate(undefined)} onCancel={() => setConfirmRun(false)} />
+    </div>
+  );
+}

package/blocks/agents/lib/agent-types.ts

@@ -0,0 +1,114 @@
+"use client";
+
+/**
+ * Shapes the agents block reads from the graph8 API, plus the small helpers every component uses to
+ * read them. The API answers `{ data: ... }`; several voice and skills routes return the service's
+ * own body inside `data` (or, for skills, at the top level), so the helpers accept both.
+ */
+
+import type { G8Envelope } from "@/g8/lib/g8-client";
+
+export interface AgentSummary {
+  agent_id: string;
+  agent_name: string;
+  role: string;
+  agent_status: "active" | "inactive" | "archived" | string;
+  entity_type?: string;
+  description?: string | null;
+  voice?: string | null;
+  phone?: string | null;
+  use_company_knowledge?: boolean;
+  collection_count?: number;
+}
+
+export interface AgentPersona {
+  agent_name: string;
+  persona: string;
+  description: string;
+  formality_level: number;
+  conciseness_level: number;
+  assertiveness_level: number;
+  inbound_instructions?: string | null;
+  outbound_instructions?: string | null;
+  outbound_voicemail_prompt?: string | null;
+  company_name_pronunciation?: string | null;
+}
+
+export interface AgentIdentity {
+  voice?: string | null;
+  phone?: string | null;
+  calendar?: number | null;
+  avatar_url?: string | null;
+}
+
+export interface AgentDetail {
+  agent_id: string;
+  agent_status: string;
+  role: string;
+  entity_type?: string;
+  persona: AgentPersona;
+  identity: AgentIdentity;
+  knowledge?: { collections?: string[] } | null;
+  use_company_knowledge: boolean;
+}
+
+export interface SkillRow {
+  action_id: string;
+  name: string;
+  description?: string | null;
+  runtime_type?: "llm" | "api" | string;
+  category?: string | null;
+  llm_config?: { prompt?: string; model?: string } | null;
+}
+
+export interface AgentRun {
+  work_item_id: string;
+  agent_id: string;
+  title: string;
+  status: string;
+  current_step?: string | null;
+  next_action?: string | null;
+  credits_spent?: number;
+  credit_budget?: number | null;
+  created_at?: string;
+  completed_at?: string | null;
+}
+
+export const DEFAULT_PERSONA: AgentPersona = {
+  agent_name: "",
+  persona: "",
+  description: "",
+  formality_level: 0.5,
+  conciseness_level: 0.5,
+  assertiveness_level: 0.5,
+};
+
+/** `data` of an envelope, or the body itself when the route did not envelope it. */
+export function bodyOf<T = Record<string, unknown>>(res: G8Envelope<unknown> | null | undefined): T {
+  const data = (res as { data?: unknown } | null | undefined)?.data;
+  return (data ?? res ?? {}) as T;
+}
+
+/** Find the first array under any of `keys` in the response body (`agents`, `items`, `actions`...). */
+export function listOf<T>(res: G8Envelope<unknown> | null | undefined, ...keys: string[]): T[] {
+  const body = bodyOf<unknown>(res);
+  if (Array.isArray(body)) return body as T[];
+  const rec = (body ?? {}) as Record<string, unknown>;
+  for (const k of keys) if (Array.isArray(rec[k])) return rec[k] as T[];
+  const top = (res ?? {}) as Record<string, unknown>;
+  for (const k of keys) if (Array.isArray(top[k])) return top[k] as T[];
+  return [];
+}
+
+export function percent(n: number | undefined): string {
+  return `${Math.round((n ?? 0) * 100)}%`;
+}
+
+/** A readable one-line summary of any JSON value, for result panels. */
+export function pretty(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}

package/blocks/agents/recipes/create-agent-and-attach-skill.ts

@@ -0,0 +1,50 @@
+/**
+ * @title Create an agent, give it a skill and some knowledge
+ * @when Building an AI agent (voice or chat) from code instead of the AgentBuilder screen. The agent id
+ * comes from the create response; skill ids come from creating or listing skills, never a guess.
+ * `persona`, `identity` and `knowledge` are replaced whole on update, so always send the full sub-object.
+ * Create it `inactive`, test it (see test-agent-before-activating.ts), then flip it to `active`.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function buildAgent() {
+  const created = await g8.api.voice.createVoiceAgent({
+    body: {
+      role: "SDR",
+      agent_status: "inactive",
+      use_company_knowledge: true,
+      identity: {},
+      persona: {
+        agent_name: "Maya",
+        description: "Qualifies inbound demo requests",
+        persona: "Warm, direct and curious. Asks one question at a time and never invents pricing.",
+        formality_level: 0.4,
+        conciseness_level: 0.7,
+        assertiveness_level: 0.5,
+      },
+    },
+  });
+  const agentId = created.data.agent?.agent_id as string | undefined;
+  if (!agentId) throw new Error("graph8 did not return an agent_id");
+
+  // A skill is a single-purpose action. runtime_type is "llm" or "api".
+  const skill = await g8.api.skills.createSkill({
+    body: {
+      name: "Summarise the lead",
+      runtime_type: "llm",
+      llm_config: { prompt: "Summarise {contact_name} in two sentences for the sales team.", model: "gpt-4o-mini" },
+    },
+  });
+  const actionId = (skill as { action_id?: string }).action_id;
+  if (actionId) await g8.api.voice.attachSkillsToAgent({ path: { agent_id: agentId }, body: { action_ids: [actionId] } });
+
+  return { agentId, actionId };
+}
+
+/** Documents are uploaded as multipart and are billable (they are embedded with a paid model). */
+export async function listAgentKnowledge(agentId: string) {
+  const docs = await g8.api.voice.listAgentDocuments({ path: { agent_id: agentId } });
+  return docs.data;
+}

package/blocks/agents/recipes/run-and-follow-agent-run.ts

@@ -0,0 +1,46 @@
+/**
+ * @title Start an agent run, poll it to the end and decide its approvals
+ * @when Handing a goal to an agent and following it. There are no streams: poll `getAgentRun` with
+ * backoff. A run can stop on an approval before it acts (send, spend, change data); decide it with a
+ * person's say-so, then keep polling. `workflow_started: false` on create is normal: the row is saved
+ * and the worker picks it up. Specialist ids come from `listAgentSpecialists`, never a guess.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const TERMINAL = new Set(["completed", "succeeded", "failed", "cancelled", "canceled"]);
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+export async function runToCompletion(goal: string, title: string) {
+  const bench = await g8.api.agents.listAgentSpecialists();
+  const first = (bench.data.items?.[0] ?? {}) as { agent_id?: string; id?: string };
+  const agentId = first.agent_id ?? first.id;
+  if (!agentId) throw new Error("No specialist available");
+
+  const created = await g8.api.agent.createAgentRun({ body: { agent_id: agentId, title, goal } });
+  const runId = created.data.work_item_id;
+
+  let delay = 2000;
+  for (let attempt = 0; attempt < 60; attempt++) {
+    const run = await g8.api.agent.getAgentRun({ path: { run_id: runId } });
+    if (TERMINAL.has(String(run.data.status).toLowerCase())) return run.data;
+    delay = Math.min(delay * 1.5, 15000);
+    await sleep(delay);
+  }
+  throw new Error("Run still going; check it later with getAgentRun");
+}
+
+/** Pending approvals for a person to read. Approving is `decision: "approve"`, a write on workflows:write. */
+export async function pendingApprovals() {
+  const res = await g8.api.agent.listAgentApprovals();
+  return res.data.filter((a) => !a.decision && !a.is_expired);
+}
+
+export async function decide(approvalId: string, decision: "approve" | "reject") {
+  return g8.api.agent.decideAgentApproval({ path: { approval_id: approvalId }, body: { decision } });
+}
+
+export async function stop(runId: string) {
+  return g8.api.agent.cancelAgentRun({ path: { run_id: runId } });
+}

package/blocks/agents/recipes/test-agent-before-activating.ts

@@ -0,0 +1,36 @@
+/**
+ * @title Save test cases, run the regression sweep and read the activation gate
+ * @when Before setting an agent `active`. Dry runs spend nothing: they resolve what the agent WOULD
+ * receive (instructions, tools, grounding) and judge an assertion, with no model call and no message sent.
+ * A case is a user turn plus an assertion: contains, not_contains, exact, refuses, expects_tool,
+ * cites_collection. `run-all` re-runs every saved case and recomputes the gate.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function gateAgent(agentId: string) {
+  await g8.api.voice.createAgentTestCase({
+    path: { agent_id: agentId },
+    body: {
+      name: "Never quotes a price",
+      input_message: "How much does it cost?",
+      channel: "chat",
+      assertion_type: "not_contains",
+      expected_output: "$",
+    },
+  });
+
+  const sweep = await g8.api.voice.runAllAgentTests({ path: { agent_id: agentId }, body: {} });
+  const gate = await g8.api.voice.getAgentTestSuiteStatus({ path: { agent_id: agentId } });
+  return { sweep: sweep.data, gate: gate.data };
+}
+
+/** One ad-hoc dry run, no saved case. Exactly one of test_case_id and input_message. */
+export async function tryOnce(agentId: string, message: string) {
+  const run = await g8.api.voice.runAgentTest({
+    path: { agent_id: agentId },
+    body: { input_message: message, channel: "chat", mode: "dry_run" },
+  });
+  return run.data;
+}

package/blocks/analytics/README.md

@@ -0,0 +1,73 @@
+# analytics: KPIs, leaderboard, funnels and reports
+
+Read-only outbound analytics (top-line numbers, rep ranking, funnels) plus a builder for saved custom-object
+reports. Depends only on the foundation. Install with `npx @graph8/sdk add analytics`.
+
+## The flow, in order
+
+1. **Tiles** `GET /analytics/outbound/summary?days=` (`KpiTiles`): `emails_sent`, `delivery_rate`,
+   `reply_rate`, `calls_dispatched`, `connect_rate`, `meetings_booked`, `meetings_active`, ... Rates are
+   **percentages** (12.5, not 0.125).
+2. **Ranking** `GET /analytics/outbound/sdr-activity/leaderboard?days=&limit=` (`Leaderboard`): rows
+   `{ sdr_email, emails_sent, replies, bounced, reply_rate, meetings_booked }`, ranked by reply rate. A rep
+   appears only after 10 emails sent in the window.
+3. **Funnel** (`FunnelChart`): `GET /analytics/outbound/meeting-funnel?days=` (booked -> still on the calendar ->
+   attended) or `GET /analytics/team/conversion-funnel?period_days=` (accounts -> contacted -> ... -> won).
+4. **Reports** (`ReportBuilder`): `GET /reports?object_slug=` lists saved reports; `POST /reports/preview`
+   runs an unsaved definition; `POST /reports` saves it; `POST /reports/{id}/execute` runs a saved one;
+   `PATCH /reports/{id}` (with `expected_revision`) edits; `DELETE /reports/{id}` archives (destructive,
+   confirmed). `config` is `{ measures: [{ kind: "count" | "sum" | "avg" | "min" | "max", attribute_slug? }],
+   group_by: [{ kind: "attribute", attribute_slug } | { kind: "created_at", grain }], filters: [] }`.
+
+IDs passed between steps: `object_slug` (objects block -> list/preview/create), `report.id` + `report.revision`
+(list -> execute/update/delete).
+
+## Response shape: read this once
+
+Most reports come back as `{ data: { success, data: <report>, meta: { cached, stale, days } } }`, so the report is
+at `res.data.data`. The revenue team reports (`/analytics/team/*`) return the report directly at `res.data`.
+`lib/analytics-types.ts` `reportBody()` handles both; recipes do it by hand. If `meta.stale` is true the numbers
+come from a cache after a failed refresh: the components say so instead of hiding it.
+
+## Prerequisites a human must do
+
+- Give the key `analytics:read`; ReportBuilder also needs `objects:read`, `objects:write`, `objects:delete`.
+- Custom-object reports are **switched on per organisation** (`where: "app"`/graph8 support). While off, every
+  `/reports` call is a 404 and ReportBuilder shows "Reports are not enabled".
+- The charts have nothing to show until the org has sent email, placed calls or booked meetings. Do not fake data.
+
+## Defaults (the agent does not need to ask)
+
+- 30-day window with 7 and 90 as alternatives; outbound reply-rate leaderboard; meetings funnel.
+- Plain-div bars, no chart library. Use `@graph8/sdk/ui`'s chart primitives if you want line charts.
+- Saved reports are private. Ask the human only about **sharing a report with the whole org** (admin key).
+
+## Gotchas
+
+- The dialer's call leaderboard (`GET /analytics/dialer/leaderboard`) and the SDR roll-up
+  (`GET /analytics/sdr/leaderboard`) are different reports with different numbers; this block ranks outbound email.
+- `meetings_held` is a legacy alias for booked-minus-cancelled, not attendance; use `meetings_active` or
+  `meetings_attended`.
+- Preview and execute are tier `write` in the contract (they create run records) but send nothing; they share the
+  org's report-run slots (429 `too_many_report_runs`: retry shortly).
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `analytics.getOutboundSummary` | GET /analytics/outbound/summary | read | KpiTiles |
+| `analytics.getSdrLeaderboard` | GET /analytics/outbound/sdr-activity/leaderboard | read | Leaderboard |
+| `analytics.getMeetingFunnel` | GET /analytics/outbound/meeting-funnel | read | FunnelChart |
+| `revenueAnalytics.getTeamConversionFunnel` | GET /analytics/team/conversion-funnel | read | FunnelChart |
+| `reports.listObjectReportsApi` | GET /reports | read | ReportBuilder |
+| `reports.previewObjectReportApi` | POST /reports/preview | write | ReportBuilder |
+| `reports.createObjectReportApi` | POST /reports | write | ReportBuilder |
+| `reports.updateObjectReportApi` | PATCH /reports/{id} | write | ReportBuilder |
+| `reports.executeObjectReportApi` | POST /reports/{id}/execute | write | ReportBuilder |
+| `reports.archiveObjectReportApi` | DELETE /reports/{id} | destructive | ReportBuilder |
+
+## Recipes (server side)
+
+- `01-weekly-outbound-report.ts`: KPIs, leaderboard, meeting funnel.
+- `02-revenue-snapshot.ts`: team dashboard, conversion funnel, forecast.
+- `03-saved-report.ts`: define, preview, save and run a custom-object report.