@graph8/sdk 0.362.0 → 0.373.0

package/blocks/agents/components/name-dialog.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+/** NameDialog: a small dialog that asks for one name (the copy of an agent, a template). Used by the duplicate and save-as-template buttons. SDK operations: none. */
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+
+export interface NameDialogProps {
+  open: boolean;
+  title: string;
+  description: string;
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  confirm: string;
+  busy: boolean;
+  error: unknown;
+  onCancel: () => void;
+  onConfirm: () => void;
+}
+
+export function NameDialog({ open, title, description, label, value, onChange, confirm, busy, error, onCancel, onConfirm }: NameDialogProps) {
+  return (
+    <Dialog open={open} onOpenChange={(o) => !o && !busy && onCancel()}>
+      <DialogContent>
+        <DialogHeader><DialogTitle>{title}</DialogTitle><DialogDescription>{description}</DialogDescription></DialogHeader>
+        <div className="flex flex-col gap-1"><Label htmlFor="agent-action-name">{label}</Label><Input id="agent-action-name" value={value} onChange={(e) => onChange(e.target.value)} /></div>
+        {error ? <ApiError error={error} title="That did not work" /> : null}
+        <DialogFooter><Button variant="ghost" disabled={busy} onClick={onCancel}>Cancel</Button><Button loading={busy} disabled={!value.trim()} onClick={onConfirm}>{confirm}</Button></DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/blocks/agents/components/receptionist-button.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+/**
+ * ReceptionistButton: set up the workspace receptionist (an agent that answers inbound calls) and switch it on or off. There is no call that
+ * reads whether it is on, so Turn on and Turn off are explicit and safe to repeat. Turning it on lets it answer real callers, so on and off
+ * go through ConfirmSpendDialog (external).
+ *
+ * SDK operations, in order:
+ *   1. ensureReceptionistAgent   POST  /voice/agents/receptionist                    (write)  creates it when missing
+ *   2. toggleReceptionistAgent   PATCH /voice/agents/receptionist?enabled             (write, confirmed as external)
+ */
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } 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 { g8Patch, g8Post } from "@/g8/lib/g8-client";
+
+export function ReceptionistButton() {
+  const [open, setOpen] = useState(false);
+  const [pending, setPending] = useState<boolean | null>(null);
+  const [result, setResult] = useState<string | null>(null);
+  const ensure = useG8Mutation(() => g8Post("/voice/agents/receptionist", {}), { onSuccess: () => setResult("The receptionist is set up. Turn it on when it is ready to take calls.") });
+  const toggle = useG8Mutation((enabled: boolean) => g8Patch("/voice/agents/receptionist", {}, { query: { enabled } }), { onSuccess: (_r, on) => { setPending(null); setResult(on ? "The receptionist is on." : "The receptionist is off.") }, onError: () => setPending(null) });
+  return (
+    <>
+      <Button variant="outline" onClick={() => { setResult(null); ensure.reset(); toggle.reset(); setOpen(true); }}>Receptionist</Button>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>Receptionist</DialogTitle><DialogDescription>An agent that answers your inbound calls and routes them. Set it up once, then switch it on or off.</DialogDescription></DialogHeader>
+          {result ? <p role="status" className="text-sm">{result}</p> : null}
+          {ensure.error ? <ApiError error={ensure.error} title="Could not set up the receptionist" /> : null}
+          {toggle.error ? <ApiError error={toggle.error} title="Could not change the receptionist" /> : null}
+          <DialogFooter className="gap-2">
+            <Button variant="outline" loading={ensure.loading} onClick={() => void ensure.mutate(undefined)}>Set up</Button>
+            <Button variant="outline" onClick={() => setPending(false)}>Turn off</Button>
+            <Button onClick={() => setPending(true)}>Turn on</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <ConfirmSpendDialog open={pending != null} tier="external" title={pending ? "Turn the receptionist on" : "Turn the receptionist off"}
+        description={pending ? "The receptionist starts answering real callers on your numbers." : "Inbound calls stop going to the receptionist."}
+        confirmLabel={pending ? "Turn on" : "Turn off"} confirming={toggle.loading} onConfirm={() => pending != null && void toggle.mutate(pending)} onCancel={() => setPending(null)} />
+    </>
+  );
+}

package/blocks/agents/components/save-as-template-button.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+/**
+ * SaveAsTemplateButton: keep an agent as a reusable template of this workspace; anyone can start a new agent from it (FromTemplateButton).
+ *
+ * SDK operations:
+ *   saveAgentAsTemplate   POST /voice/agents/{agent_id}/save-as-template?template_name   (write)
+ */
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import type { AgentSummary } from "../lib/agent-types";
+import { NameDialog } from "./name-dialog";
+
+export interface SaveAsTemplateButtonProps {
+  agent: Pick<AgentSummary, "agent_id" | "agent_name">;
+  variant?: "outline" | "ghost";
+}
+
+export function SaveAsTemplateButton({ agent, variant = "outline" }: SaveAsTemplateButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [name, setName] = useState("");
+  const save = useG8Mutation((n: string) => g8Post(`/voice/agents/${encodeURIComponent(agent.agent_id)}/save-as-template`, {}, { query: { template_name: n } }), { onSuccess: () => setOpen(false) });
+  return (
+    <>
+      <Button size="sm" variant={variant} onClick={() => { save.reset(); setName(agent.agent_name); setOpen(true); }}>Save as template</Button>
+      <NameDialog open={open} title={`Save ${agent.agent_name} as a template`} description="Anyone in the workspace can start a new agent from it." label="Template name"
+        value={name} onChange={setName} confirm="Save template" busy={save.loading} error={save.error} onCancel={() => setOpen(false)} onConfirm={() => void save.mutate(name.trim())} />
+    </>
+  );
+}

package/blocks/agents/components/skill-editor.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+/**
+ * SkillEditor: create or edit one skill (a single-purpose action an agent can run) in a side sheet.
+ *   Edit:   the skill is loaded first and the form stays disabled until it has loaded (a blank form never overwrites the real skill);
+ *           Save sends only the fields you changed (a runtime config goes whole, because voice validates it as a unit).
+ *           Also: enable or disable, see the {placeholders} the skill asks for, check a template, delete.
+ *   Create: an LLM skill (model + prompt) or an API skill (endpoint, method, headers, body).
+ * Deleting a skill removes it from every agent that uses it, so it is destructive and confirmed.
+ *
+ * SDK operations, in order:
+ *   1. getSkill         GET    /skills/{action_id}                (read)
+ *   2. extractVariables GET    /skills/{action_id}/variables      (read)
+ *   3. listModels       GET    /skills/models                     (read)  LLM model choices
+ *   4. validateTemplate POST   /skills/validate { template | runtime_type + config }   (write, free: warns about double braces)
+ *   5. createSkill      POST   /skills { name, runtime_type, llm_config | api_config }  (write)
+ *   6. updateSkill      PUT    /skills/{action_id} { changed fields }                  (write)
+ *   7. deleteSkill      DELETE /skills/{action_id}                (destructive, ConfirmSpendDialog)
+ */
+import { useEffect, useRef, 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 { FormSheet } from "@/g8/components/screen/form-sheet";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import { BLANK_DRAFT, HTTP_METHODS, draftOf, newSkillBody, parseHeaders, skillOf, skillPatch } from "../lib/skill-utils";
+import type { SkillDraft } from "../lib/skill-utils";
+
+export type SkillEditorTarget = { kind: "edit"; id: string } | { kind: "new"; runtime: "llm" | "api" };
+
+export interface SkillEditorProps {
+  /** The skill to edit or the kind to create; null closes the sheet. */
+  target: SkillEditorTarget | null;
+  onClose: () => void;
+  /** After a create, save or delete. */
+  onChanged?: (event: "created" | "updated" | "deleted", id?: string) => void;
+}
+
+export function SkillEditor({ target, onClose, onChanged }: SkillEditorProps) {
+  const editId = target?.kind === "edit" ? target.id : "";
+  const runtime = target?.kind === "new" ? target.runtime : undefined;
+  const [d, setD] = useState<SkillDraft>(BLANK_DRAFT);
+  const [deleting, setDeleting] = useState(false);
+  const seeded = useRef<string>("");
+  const loaded = useG8Query((signal) => g8Get(`/skills/${encodeURIComponent(editId)}`, undefined, { signal }), [editId], { enabled: Boolean(editId) });
+  // useG8Query keeps the previous skill's data while the next loads: only the skill fetched for THIS id counts as loaded.
+  const got = editId ? skillOf(loaded.data) : undefined;
+  const skill = got && got.action_id === editId ? got : undefined;
+  const vars = useG8Query((signal) => g8Get(`/skills/${encodeURIComponent(editId)}/variables`, undefined, { signal }), [editId], { enabled: Boolean(editId) && Boolean(skill) });
+  const kind = skill?.runtime_type ?? runtime;
+  const models = useG8Query((signal) => g8Get("/skills/models", undefined, { signal }), [], { enabled: kind === "llm" });
+  const set = (patch: Partial<SkillDraft>) => setD((x) => ({ ...x, ...patch }));
+
+  // Seed the form from the LOADED skill, once per skill (a refetch must not overwrite what the person is typing).
+  useEffect(() => {
+    if (target?.kind === "new") { seeded.current = "new"; setD(BLANK_DRAFT); setDeleting(false); return; }
+    if (skill && seeded.current !== skill.action_id) { seeded.current = skill.action_id; setD(draftOf(skill)); }
+  }, [target, skill]);
+  useEffect(() => { if (!target) { seeded.current = ""; } }, [target]);
+
+  const patch = skill ? skillPatch(skill, d) : {};
+  const headersOk = d.headers.trim() === "" || parseHeaders(d.headers) != null;
+  const numbersOk = kind !== "llm" || (Number.isFinite(Number(d.temperature)) && Number(d.max_tokens) > 0);
+  const filled = d.name.trim() && (kind === "llm" ? d.model && d.prompt_template.trim() : d.endpoint.trim());
+  const valid = Boolean(filled) && headersOk && numbersOk;
+
+  const create = useG8Mutation(async () => {
+    const res = await g8Post("/skills", newSkillBody(kind as "llm" | "api", d));
+    return skillOf(res)?.action_id;
+  }, { onSuccess: (id) => { onChanged?.("created", id); onClose(); } });
+  const save = useG8Mutation(() => g8Put(`/skills/${encodeURIComponent(editId)}`, patch), { onSuccess: () => { seeded.current = ""; void loaded.refetch(); void vars.refetch(); onChanged?.("updated", editId); } });
+  const remove = useG8Mutation(() => g8Delete(`/skills/${encodeURIComponent(editId)}`), { onSuccess: () => { setDeleting(false); onChanged?.("deleted", editId); onClose(); }, onError: () => setDeleting(false) });
+  const check = useG8Mutation(() => g8Post("/skills/validate", kind === "llm" ? { template: d.prompt_template } : { runtime_type: "api", api_config: { endpoint: d.endpoint, body_template: d.body_template, headers: parseHeaders(d.headers) ?? {} } }));
+
+  const modelRows = listOf<{ id: string; label?: string }>(models.data, "models");
+  const checked = bodyOf<{ variables?: string[]; warnings?: string[] }>(check.data);
+  const names = (bodyOf<{ variables?: string[] }>(vars.data).variables ?? []) as string[];
+  const waiting = Boolean(editId) && !skill;
+  const title = target?.kind === "new" ? (runtime === "api" ? "New API skill" : "New LLM skill") : skill?.name ?? "Skill";
+
+  return (
+    <>
+      <FormSheet open={target != null} onOpenChange={(o) => !o && onClose()} title={title} width="lg"
+        description={target?.kind === "new" ? "Use {variable} placeholders for values the agent fills in when it runs the skill." : "Changes apply to every agent that uses this skill."}
+        footer={<>
+          {editId ? <Button variant="ghost" className="mr-auto" disabled={!skill} onClick={() => setDeleting(true)}>Delete</Button> : null}
+          <Button variant="ghost" onClick={onClose}>Cancel</Button>
+          {target?.kind === "new" ? <Button loading={create.loading} disabled={!valid} onClick={() => void create.mutate(undefined)}>Create skill</Button>
+            : <Button loading={save.loading} disabled={!skill || Object.keys(patch).length === 0 || !valid} onClick={() => void save.mutate(undefined)}>Save changes</Button>}
+        </>}>
+        {loaded.error ? <ApiError error={loaded.error} title="Could not load the skill" onRetry={() => void loaded.refetch()} /> : null}
+        {waiting && !loaded.error ? <Skeleton className="h-40 w-full" aria-label="Loading skill" /> : null}
+        {!waiting ? (
+          <fieldset className="flex flex-col gap-3 border-0 p-0" disabled={save.loading || create.loading}>
+            <div className="flex flex-col gap-1"><Label htmlFor="sk-name">Name</Label><Input id="sk-name" value={d.name} onChange={(e) => set({ name: e.target.value })} /></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="sk-desc">What it does</Label><Input id="sk-desc" value={d.description} onChange={(e) => set({ description: e.target.value })} /></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="sk-cat">Category</Label><Input id="sk-cat" value={d.category} onChange={(e) => set({ category: e.target.value })} /></div>
+            {editId ? <label className="flex items-center gap-2 text-sm"><Switch checked={d.enabled} onCheckedChange={(v) => set({ enabled: v })} aria-label="Enabled" />Enabled</label> : null}
+            {kind === "llm" ? (
+              <>
+                <div className="flex flex-col gap-1">
+                  <Label htmlFor="sk-model">Model</Label>
+                  <select id="sk-model" className="h-9 rounded-md border bg-background px-2 text-sm" value={d.model} onChange={(e) => set({ model: e.target.value })}>
+                    <option value="">Choose a model</option>
+                    {d.model && !modelRows.some((m) => m.id === d.model) ? <option value={d.model}>{d.model}</option> : null}
+                    {modelRows.map((m) => <option key={m.id} value={m.id}>{m.label ?? m.id}</option>)}
+                  </select>
+                </div>
+                <div className="flex flex-col gap-1"><Label htmlFor="sk-prompt">Prompt</Label><Textarea id="sk-prompt" rows={8} value={d.prompt_template} onChange={(e) => set({ prompt_template: e.target.value })} /></div>
+                <div className="grid grid-cols-2 gap-3">
+                  <div className="flex flex-col gap-1"><Label htmlFor="sk-temp">Temperature (0 to 2)</Label><Input id="sk-temp" inputMode="decimal" value={d.temperature} onChange={(e) => set({ temperature: e.target.value })} /></div>
+                  <div className="flex flex-col gap-1"><Label htmlFor="sk-max">Max tokens</Label><Input id="sk-max" inputMode="numeric" value={d.max_tokens} onChange={(e) => set({ max_tokens: e.target.value })} /></div>
+                </div>
+              </>
+            ) : (
+              <>
+                <div className="grid grid-cols-[7rem_1fr] gap-3">
+                  <div className="flex flex-col gap-1"><Label htmlFor="sk-method">Method</Label>
+                    <select id="sk-method" className="h-9 rounded-md border bg-background px-2 text-sm" value={d.method} onChange={(e) => set({ method: e.target.value })}>{HTTP_METHODS.map((m) => <option key={m} value={m}>{m}</option>)}</select></div>
+                  <div className="flex flex-col gap-1"><Label htmlFor="sk-endpoint">Endpoint</Label><Input id="sk-endpoint" placeholder="https://api.example.com/items/{item_id}" value={d.endpoint} onChange={(e) => set({ endpoint: e.target.value })} /></div>
+                </div>
+                <div className="flex flex-col gap-1"><Label htmlFor="sk-headers">Headers (JSON)</Label><Textarea id="sk-headers" rows={3} className="font-mono text-xs" value={d.headers} onChange={(e) => set({ headers: e.target.value })} /></div>
+                {!headersOk ? <p role="alert" className="text-sm text-error-foreground">Headers must be a JSON object of text values.</p> : null}
+                <div className="flex flex-col gap-1"><Label htmlFor="sk-body">Body template</Label><Textarea id="sk-body" rows={4} className="font-mono text-xs" value={d.body_template} onChange={(e) => set({ body_template: e.target.value })} /></div>
+                <label className="flex items-center gap-2 text-sm"><Switch checked={d.requires_auth} onCheckedChange={(v) => set({ requires_auth: v })} aria-label="Requires auth" />Requires authentication</label>
+              </>
+            )}
+            {names.length ? <p className="text-xs text-muted-foreground">Asks for: {names.map((n) => `{${n}}`).join(", ")}</p> : null}
+            <div className="flex items-center gap-2">
+              <Button size="sm" variant="outline" loading={check.loading} disabled={kind === "llm" ? !d.prompt_template.trim() : !d.endpoint.trim()} onClick={() => void check.mutate(undefined)}>Check placeholders</Button>
+              {check.data !== undefined ? <span role="status" className="text-xs text-muted-foreground">{(checked.variables ?? []).length} placeholders{(checked.warnings ?? []).length ? `, ${(checked.warnings ?? []).join(" ")}` : ", no warnings"}</span> : null}
+            </div>
+            {check.error ? <ApiError error={check.error} title="Could not check the template" /> : null}
+            {create.error ? <ApiError error={create.error} title="Could not create the skill" /> : null}
+            {save.error ? <ApiError error={save.error} title="Could not save the skill" /> : null}
+            {remove.error ? <ApiError error={remove.error} title="Could not delete the skill" /> : null}
+          </fieldset>
+        ) : null}
+      </FormSheet>
+      <ConfirmSpendDialog open={deleting} tier="destructive" title={`Delete "${skill?.name ?? "this skill"}"`} description="Every agent that uses it loses it, and workflows that call it stop working." affected={1}
+        confirmLabel="Delete" confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setDeleting(false)} />
+    </>
+  );
+}

package/blocks/agents/components/skill-library.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+/**
+ * SkillLibrary: every skill in the workspace (your own plus graph8's defaults) in one list. Search by name, filter by kind
+ * and by enabled, open one to edit it (SkillEditor), write a new LLM or API skill, or start from a template. A skill that no
+ * agent uses yet can be attached from an agent's Skills tab.
+ *
+ * SDK operations, in order:
+ *   1. listSkills          GET  /skills?runtime_type&enabled&include_system   (read)  returns every skill, no cap
+ *   2. listTemplates       GET  /skills/templates                              (read)
+ *   3. createFromTemplate  POST /skills/from-template { template_id, name }    (write)
+ *   4. SkillEditor         see skill-editor.tsx (getSkill, updateSkill, deleteSkill, createSkill, validateTemplate, extractVariables, listModels)
+ */
+import { useMemo, useRef, useState } from "react";
+import { Wand2 } from "lucide-react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+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 { listOf } from "../lib/agent-types";
+import type { SkillDetail } from "../lib/skill-utils";
+import { skillOf } from "../lib/skill-utils";
+import { SkillEditor } from "./skill-editor";
+import type { SkillEditorTarget } from "./skill-editor";
+
+export interface SkillLibraryProps {
+  className?: string;
+}
+
+interface Template { template_id?: string; action_id?: string; id?: string; name: string; description?: string | null; runtime_type?: string }
+const tid = (t: Template): string => t.template_id ?? t.action_id ?? t.id ?? "";
+const KINDS = [{ id: "", label: "All" }, { id: "llm", label: "LLM" }, { id: "api", label: "API" }];
+const STATES = [{ id: "", label: "Any state" }, { id: "true", label: "Enabled" }, { id: "false", label: "Disabled" }];
+
+function FromTemplate({ open, onClose, onCreated }: { open: boolean; onClose: () => void; onCreated: (id?: string) => void }) {
+  const [picked, setPicked] = useState<Template | null>(null);
+  const [name, setName] = useState("");
+  const made = useRef<{ id?: string } | null>(null);
+  const templates = useG8Query((signal) => g8Get("/skills/templates", undefined, { signal }), [], { enabled: open });
+  const create = useG8Mutation(async (v: { id: string; name: string }) => {
+    if (made.current) return made.current.id;
+    const id = skillOf(await g8Post("/skills/from-template", { template_id: v.id, name: v.name }))?.action_id;
+    made.current = { id };
+    return id;
+  }, { onSuccess: (id) => { made.current = null; setPicked(null); onCreated(id); } });
+  const rows = listOf<Template>(templates.data, "actions", "templates", "items");
+  return (
+    <Dialog open={open} onOpenChange={(o) => !o && !create.loading && onClose()}>
+      <DialogContent>
+        <DialogHeader><DialogTitle>New skill from a template</DialogTitle><DialogDescription>Templates are ready-made skills. Name yours and edit it afterwards.</DialogDescription></DialogHeader>
+        {templates.error ? <ApiError error={templates.error} title="Could not load templates" onRetry={() => void templates.refetch()} /> : null}
+        {templates.loading && !templates.data ? <Skeleton className="h-16 w-full" /> : null}
+        <ul className="max-h-64 divide-y overflow-y-auto rounded-md border">
+          {rows.map((t) => (
+            <li key={tid(t)}><button type="button" aria-pressed={picked != null && tid(picked) === tid(t)} className={`block w-full px-3 py-2 text-left text-sm ${picked != null && tid(picked) === tid(t) ? "bg-accent" : ""}`} onClick={() => { made.current = null; setPicked(t); setName(t.name); }}>
+              <span className="font-medium">{t.name}</span>{t.runtime_type ? <span className="ml-2 text-xs text-muted-foreground">{t.runtime_type}</span> : null}
+              {t.description ? <span className="block text-xs text-muted-foreground">{t.description}</span> : null}
+            </button></li>
+          ))}
+        </ul>
+        {!templates.loading && !templates.error && rows.length === 0 ? <p className="text-sm text-muted-foreground">There are no templates yet.</p> : null}
+        {picked ? <div className="flex flex-col gap-1"><Label htmlFor="skill-from-template">Name</Label><Input id="skill-from-template" value={name} onChange={(e) => setName(e.target.value)} /></div> : null}
+        {create.error ? <ApiError error={create.error} title="Could not create the skill" /> : null}
+        <DialogFooter><Button variant="ghost" disabled={create.loading} onClick={onClose}>Cancel</Button><Button loading={create.loading} disabled={!picked || !name.trim()} onClick={() => picked && void create.mutate({ id: tid(picked), name: name.trim() })}>Create skill</Button></DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export function SkillLibrary({ className }: SkillLibraryProps) {
+  const [search, setSearch] = useState("");
+  const [kind, setKind] = useState("");
+  const [state, setState] = useState("");
+  const [target, setTarget] = useState<SkillEditorTarget | null>(null);
+  const [fromTemplate, setFromTemplate] = useState(false);
+  const skills = useG8Query((signal) => g8Get("/skills", { runtime_type: kind || undefined, enabled: state || undefined, include_system: true }, { signal }), [kind, state]);
+  const all = listOf<SkillDetail>(skills.data, "actions", "skills", "items");
+  const q = search.trim().toLowerCase();
+  const rows = useMemo(() => (q ? all.filter((s) => `${s.name} ${s.description ?? ""} ${s.category ?? ""}`.toLowerCase().includes(q)) : all), [all, q]);
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <Toolbar search={{ value: search, onChange: setSearch, placeholder: "Search skills" }}
+        filters={<><div role="group" aria-label="Skill kind" className="flex gap-1">{KINDS.map((k) => <Button key={k.id || "all"} size="sm" variant={kind === k.id ? "default" : "outline"} onClick={() => setKind(k.id)}>{k.label}</Button>)}</div>
+          <select aria-label="Skill state" className="h-8 rounded-md border bg-background px-2 text-sm" value={state} onChange={(e) => setState(e.target.value)}>{STATES.map((s) => <option key={s.id} value={s.id}>{s.label}</option>)}</select></>}
+        actions={<><Button size="sm" variant="outline" onClick={() => setFromTemplate(true)}>From a template</Button><Button size="sm" variant="outline" onClick={() => setTarget({ kind: "new", runtime: "api" })}>New API skill</Button><Button size="sm" onClick={() => setTarget({ kind: "new", runtime: "llm" })}>New LLM skill</Button></>} />
+      {skills.error ? <ApiError error={skills.error} title="Could not load skills" onRetry={() => void skills.refetch()} /> : null}
+      {skills.loading && !skills.data ? <div className="space-y-2">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-12 w-full" />)}</div> : null}
+      <ul className="divide-y rounded-md border">
+        {rows.map((s) => (
+          <li key={s.action_id}>
+            <button type="button" data-testid={`skill-${s.action_id}`} className="flex w-full items-center justify-between gap-3 px-3 py-2 text-left text-sm" onClick={() => setTarget({ kind: "edit", id: s.action_id })}>
+              <span className="min-w-0"><span className="block truncate font-medium">{s.name}</span>{s.description ? <span className="block truncate text-xs text-muted-foreground">{s.description}</span> : null}</span>
+              <span className="flex shrink-0 items-center gap-2">{s.category ? <span className="text-xs text-muted-foreground">{s.category}</span> : null}<StatusPill tone="neutral">{s.runtime_type ?? "skill"}</StatusPill><StatusPill tone={s.enabled === false ? "warning" : "positive"} dot>{s.enabled === false ? "disabled" : "enabled"}</StatusPill></span>
+            </button>
+          </li>
+        ))}
+      </ul>
+      {!skills.loading && !skills.error && rows.length === 0 ? (
+        <EmptyState icon={<Wand2 strokeWidth={1.5} />} title={all.length ? "No skills match" : "No skills yet"} description="A skill is one thing an agent can do: write a summary, call an API."
+          action={all.length ? undefined : <Button onClick={() => setTarget({ kind: "new", runtime: "llm" })}>New LLM skill</Button>} />
+      ) : null}
+      <SkillEditor target={target} onClose={() => setTarget(null)} onChanged={() => void skills.refetch()} />
+      <FromTemplate open={fromTemplate} onClose={() => setFromTemplate(false)} onCreated={(id) => { setFromTemplate(false); void skills.refetch(); if (id) setTarget({ kind: "edit", id }); }} />
+    </div>
+  );
+}

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

@@ -58,7 +58,7 @@ export interface SkillRow {
   description?: string | null;
   runtime_type?: "llm" | "api" | string;
   category?: string | null;
-  llm_config?: { prompt?: string; model?: string } | null;
+  llm_config?: { prompt_template?: string; model?: string } | null;
 }
 
 export interface AgentRun {
@@ -112,3 +112,9 @@ export function pretty(value: unknown): string {
     return String(value);
   }
 }
+
+/** The id of the agent a create or clone answered with, whatever envelope it came in. */
+export function agentIdOf(res: G8Envelope<unknown> | null | undefined): string {
+  const b = bodyOf<{ agent?: { agent_id?: string }; agent_id?: string; new_agent_id?: string }>(res);
+  return b.agent?.agent_id ?? b.agent_id ?? b.new_agent_id ?? "";
+}

package/blocks/agents/lib/facts.tsx

@@ -0,0 +1,13 @@
+"use client";
+
+/** Renders an open-shaped API object (health, scorecard, status) as labelled facts without guessing its fields. */
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+
+const label = (k: string): string => { const t = k.replace(/_/g, " "); return t.charAt(0).toUpperCase() + t.slice(1); };
+const show = (v: unknown): string => (v == null ? "" : typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : JSON.stringify(v));
+
+export function FactList({ data, empty = "Nothing reported yet." }: { data: unknown; empty?: string }) {
+  const entries = Object.entries((data && typeof data === "object" && !Array.isArray(data) ? data : {}) as Record<string, unknown>).filter(([, v]) => v != null && v !== "");
+  if (entries.length === 0) return <p className="text-sm text-muted-foreground">{empty}</p>;
+  return <KeyValueList columns={2} items={entries.map(([k, v]) => ({ label: label(k), value: show(v), wide: typeof v === "object", mono: typeof v === "object" }))} />;
+}

package/blocks/agents/lib/knowledge-utils.ts

@@ -0,0 +1,49 @@
+"use client";
+
+/** Shapes of the company knowledge (the Knowledge Brain) the agents block reads, and the body helpers for authoring. */
+
+export interface KnowledgeSummary {
+  concept_id: string;
+  concept_type: string;
+  title: string;
+  source_type?: string;
+  knowledge_status?: string;
+  trust_tier?: string;
+  visibility?: string;
+  stale?: boolean;
+  logical_path?: string;
+}
+
+export interface KnowledgeConcept {
+  summary: KnowledgeSummary;
+  markdown?: string;
+  source_refs?: Array<{ resource?: string; title?: string | null; locator?: string | null; checksum?: string | null }>;
+  relationships?: string[];
+  warnings?: string[];
+  capabilities?: Record<string, boolean>;
+}
+
+export interface KnowledgeInput {
+  title: string;
+  concept_type: string;
+  body: string;
+}
+
+export const LIFECYCLES = ["draft", "stable", "deprecated"] as const;
+
+/** Rendered markdown can start with a `---` frontmatter block; the authoring body must not carry it. */
+export function bodyFromMarkdown(markdown: string | undefined): string {
+  const text = markdown ?? "";
+  const m = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(text);
+  return (m ? text.slice(m[0].length) : text).replace(/^\s+/, "");
+}
+
+/** Only authored entries can be edited, amended, verified or deprecated; generated ones come from the product's own records. */
+export function isAuthored(s: KnowledgeSummary | undefined): boolean {
+  return Boolean(s?.source_type && /authored/i.test(s.source_type));
+}
+
+export function conceptOf(res: unknown): KnowledgeConcept | undefined {
+  const d = ((res as { data?: unknown } | null)?.data ?? res) as Partial<KnowledgeConcept> | null;
+  return d && d.summary && d.summary.concept_id ? (d as KnowledgeConcept) : undefined;
+}

package/blocks/agents/lib/load-more.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+/**
+ * Paging helpers for the agents block, in the same shape as the foundation's paging primitives (a list never stops silently at a
+ * cap: it shows "Load more" while the last page was full).
+ *
+ *   useLoadMoreList   offset + limit APIs (the next page starts at items.length).
+ *   useGrowingList    limit-only APIs (a bigger limit refetches the list from the start).
+ *   LoadMore          the footer button plus the error of a failed "more" request.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+
+export interface LoadMoreList<T> {
+  items: T[];
+  /** The first page is loading (or reloading after the deps changed). */
+  loading: boolean;
+  loadingMore: boolean;
+  error: unknown;
+  moreError: unknown;
+  hasMore: boolean;
+  /** A limit-only API stopped at its own maximum: there are more rows the API will not return. */
+  capped?: boolean;
+  loadMore: () => void;
+  reload: () => void;
+}
+
+interface Options {
+  pageSize?: number;
+  enabled?: boolean;
+  /** useGrowingList: the largest `limit` the API accepts. */
+  max?: number;
+}
+
+/** Offset paging. `fetchPage(offset, limit)` returns that page's rows; a full page means there may be more. */
+export function useLoadMoreList<T>(
+  fetchPage: (offset: number, limit: number, signal: AbortSignal) => Promise<T[]>,
+  deps: readonly unknown[],
+  { pageSize = 50, enabled = true }: Options = {},
+): LoadMoreList<T> {
+  const [items, setItems] = useState<T[]>([]);
+  const [loading, setLoading] = useState(enabled);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [error, setError] = useState<unknown>(null);
+  const [moreError, setMoreError] = useState<unknown>(null);
+  const [hasMore, setHasMore] = useState(false);
+  const [tick, setTick] = useState(0);
+  const fetchRef = useRef(fetchPage);
+  fetchRef.current = fetchPage;
+  const gen = useRef(0);
+  const count = useRef(0);
+  const sig = JSON.stringify([...deps, enabled, pageSize]);
+  const lastSig = useRef(sig);
+
+  useEffect(() => {
+    if (!enabled) { setLoading(false); return; }
+    const mine = ++gen.current;
+    const ctl = new AbortController();
+    // A reload() keeps showing the rows it has until the fresh first page lands; a changed filter starts from nothing.
+    const fresh = lastSig.current !== sig;
+    lastSig.current = sig;
+    setLoading(true); setError(null); setMoreError(null);
+    if (fresh) { setItems([]); setHasMore(false); count.current = 0; }
+    // A reload() refetches as many pages as were showing, so a row opened from page 2 does not vanish; a changed filter starts at page 1.
+    const want = fresh ? pageSize : Math.max(count.current, pageSize);
+    const load = async (): Promise<T[]> => {
+      const all: T[] = [];
+      let last = pageSize;
+      while (all.length < want && last >= pageSize) {
+        const page = await fetchRef.current(all.length, pageSize, ctl.signal);
+        all.push(...page);
+        last = page.length;
+      }
+      return all;
+    };
+    load().then((rows) => {
+      if (gen.current !== mine) return;
+      setItems(rows); count.current = rows.length; setHasMore(rows.length > 0 && rows.length % pageSize === 0); setLoading(false);
+    }, (e) => { if (gen.current === mine) { setError(e); setLoading(false); } });
+    return () => ctl.abort();
+  }, [...deps, enabled, pageSize, tick]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const loadMore = useCallback(() => {
+    const mine = gen.current;
+    setLoadingMore(true); setMoreError(null);
+    fetchRef.current(count.current, pageSize, new AbortController().signal).then((rows) => {
+      if (gen.current !== mine) return;
+      count.current += rows.length;
+      setItems((prev) => [...prev, ...rows]); setHasMore(rows.length >= pageSize); setLoadingMore(false);
+    }, (e) => { if (gen.current === mine) { setMoreError(e); setLoadingMore(false); } });
+  }, [pageSize]);
+
+  return { items, loading, loadingMore, error, moreError, hasMore, loadMore, reload: () => setTick((t) => t + 1) };
+}
+
+/** Limit-only APIs: asks for `step` rows, and "Load more" asks again for `step` more from the start. */
+export function useGrowingList<T>(
+  fetchRows: (limit: number, signal: AbortSignal) => Promise<T[]>,
+  deps: readonly unknown[],
+  { pageSize = 50, enabled = true, max = Infinity }: Options = {},
+): LoadMoreList<T> {
+  const [limit, setLimit] = useState(pageSize);
+  const [rows, setRows] = useState<T[]>([]);
+  const [loading, setLoading] = useState(enabled);
+  const [error, setError] = useState<unknown>(null);
+  const [tick, setTick] = useState(0);
+  const [growing, setGrowing] = useState(false);
+  const fetchRef = useRef(fetchRows);
+  fetchRef.current = fetchRows;
+  const depKey = JSON.stringify(deps);
+  const lastDeps = useRef(depKey);
+
+  useEffect(() => { if (lastDeps.current !== depKey) { lastDeps.current = depKey; setLimit(pageSize); } }, [depKey, pageSize]);
+  useEffect(() => {
+    if (!enabled) { setLoading(false); return; }
+    let live = true;
+    const ctl = new AbortController();
+    setLoading(true); setError(null);
+    fetchRef.current(limit, ctl.signal).then((r) => { if (live) { setRows(r); setLoading(false); setGrowing(false); } }, (e) => { if (live) { setError(e); setLoading(false); setGrowing(false); } });
+    return () => { live = false; ctl.abort(); };
+  }, [limit, depKey, enabled, tick]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return {
+    items: rows, loading: loading && !growing, loadingMore: loading && growing, error: growing ? null : error, moreError: growing ? error : null,
+    hasMore: !loading && rows.length >= limit && limit < max, capped: !loading && rows.length >= limit && limit >= max,
+    loadMore: () => { setGrowing(true); setLimit((l) => Math.min(max, l + pageSize)); }, reload: () => setTick((t) => t + 1),
+  };
+}
+
+/** The footer of a paged list. Renders nothing when everything is shown. */
+export function LoadMore<T>({ list, noun = "rows" }: { list: LoadMoreList<T>; noun?: string }) {
+  if (!list.hasMore && !list.moreError && !list.capped) return null;
+  return (
+    <div className="flex flex-col items-center gap-2 py-2">
+      {list.moreError ? <ApiError compact error={list.moreError} title={`Could not load more ${noun}`} onRetry={list.loadMore} /> : null}
+      {list.capped ? <p className="text-xs text-muted-foreground">Showing the latest {list.items.length} {noun}. The API returns no more than this.</p> : null}
+      {list.hasMore && !list.moreError ? <Button size="sm" variant="outline" loading={list.loadingMore} onClick={list.loadMore}>Load more {noun}</Button> : null}
+    </div>
+  );
+}