@graph8/sdk 0.362.0 → 0.373.0

package/blocks/agents/components/assistant-sessions.tsx

@@ -0,0 +1,150 @@
+"use client";
+
+/**
+ * AssistantSessions: conversations with the graph8 assistant (the workspace agent that answers questions and starts jobs). The list of
+ * your sessions (pinned first, "Load more" pages through all of them), a session's messages and the steps the agent took, and the
+ * actions: new session, rename, pin, delete (destructive, confirmed), add a note (no model call; the agent reads it on its next turn)
+ * and "Ask" (one live turn: the agent answers, or reads the message as a job and starts a run).
+ * A live turn runs a model and may start autonomous work that spends credits, so Ask goes through ConfirmSpendDialog (billable).
+ * Live streaming is not available through the API; an answer arrives whole.
+ *
+ * SDK operations, in order:
+ *   1. listAgentSessions       GET    /agent/sessions?limit&offset                       (read)
+ *   2. createAgentSession      POST   /agent/sessions { title? }                         (write)
+ *   3. getAgentSessionState    GET    /agent/sessions/{session_id}/state                 (read)  messages + steps
+ *   4. markAgentSessionRead    PUT    /agent/sessions/{session_id}/read { message_count } (write)
+ *   5. renameAgentSession      POST   /agent/sessions/{session_id}/rename { title }      (write)
+ *   6. pinAgentSession         POST   /agent/sessions/{session_id}/pin { is_pinned }     (write)
+ *   7. deleteAgentSession      DELETE /agent/sessions/{session_id}                       (destructive, ConfirmSpendDialog)
+ *   8. postAgentSessionMessage POST   /agent/sessions/{session_id}/messages { content }  (write, no model call)
+ *   9. postAgentChat           POST   /agent/chat { message, session_id? }               (billable, ConfirmSpendDialog)
+ */
+import { useEffect, useRef, useState } from "react";
+import { MessagesSquare, Pin } from "lucide-react";
+import { Button, Input, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import { LoadMore, useLoadMoreList } from "../lib/load-more";
+
+export interface AssistantSessionsProps {
+  /** Called when a live turn started a run, so the host can open it. */
+  onOpenRun?: (runId: string) => void;
+  className?: string;
+}
+
+interface Session { id?: string | null; title?: string | null; is_pinned?: boolean | null; updated_at?: string | null; created_at?: string | null }
+interface Message { role?: string; content?: unknown }
+interface Step { title?: string; summary?: string; tool?: string; status?: string }
+const enc = encodeURIComponent;
+const text = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : JSON.stringify(v));
+
+function Transcript({ sessionId, refreshKey }: { sessionId: string; refreshKey: number }) {
+  const state = useG8Query((signal) => g8Get(`/agent/sessions/${enc(sessionId)}/state`, undefined, { signal }), [sessionId, refreshKey]);
+  const body = bodyOf<{ messages?: Message[]; steps?: Step[] }>(state.data);
+  const messages = body.messages ?? [];
+  const lastRead = useRef<string>("");
+  const markRead = useG8Mutation((n: number) => g8Put(`/agent/sessions/${enc(sessionId)}/read`, { message_count: n }));
+  useEffect(() => {
+    const key = `${sessionId}:${messages.length}`;
+    if (state.data && messages.length > 0 && lastRead.current !== key) { lastRead.current = key; void markRead.mutate(messages.length); }
+  }, [state.data, messages.length, sessionId]); // eslint-disable-line react-hooks/exhaustive-deps
+  if (state.error) return <ApiError error={state.error} title="Could not load the session" onRetry={() => void state.refetch()} />;
+  if (state.loading && !state.data) return <Skeleton className="h-24 w-full" aria-label="Loading session" />;
+  return (
+    <div className="flex flex-col gap-3">
+      {messages.length === 0 ? <p className="text-sm text-muted-foreground">No messages in this session yet.</p> : null}
+      <ol className="flex flex-col gap-2" aria-label="Messages">
+        {messages.map((m, i) => <li key={i} className={`max-w-[85%] rounded-md border px-3 py-2 text-sm ${m.role === "user" ? "self-end bg-accent" : "self-start"}`}><span className="block text-xs text-muted-foreground">{m.role === "user" ? "You" : "Assistant"}</span><span className="whitespace-pre-wrap">{text(m.content)}</span></li>)}
+      </ol>
+      {(body.steps ?? []).length ? <details className="text-sm"><summary className="cursor-pointer text-muted-foreground">What the agent did ({body.steps?.length})</summary><ul className="mt-2 list-disc pl-5">{(body.steps ?? []).map((s, i) => <li key={i}>{s.title ?? s.summary ?? s.tool}{s.status ? ` (${s.status})` : ""}</li>)}</ul></details> : null}
+    </div>
+  );
+}
+
+export function AssistantSessions({ onOpenRun, className }: AssistantSessionsProps) {
+  const [openId, setOpenId] = useState<string | null>(null);
+  const [draft, setDraft] = useState("");
+  const [asking, setAsking] = useState<string | null>(null);
+  const [renaming, setRenaming] = useState<string | null>(null);
+  const [title, setTitle] = useState("");
+  const [deleting, setDeleting] = useState<Session | null>(null);
+  const [reply, setReply] = useState<{ message?: string; kind?: string; work_item_id?: string } | null>(null);
+  const [turnKey, setTurn] = useState(0);
+  const list = useLoadMoreList<Session>(async (offset, limit, signal) => listOf<Session>(await g8Get("/agent/sessions", { limit, offset }, { signal }), "sessions", "items"), [], { pageSize: 50 });
+  const rows = [...list.items].sort((a, b) => Number(Boolean(b.is_pinned)) - Number(Boolean(a.is_pinned)));
+  const open = rows.find((s) => s.id === openId) ?? null;
+
+  const create = useG8Mutation(async () => bodyOf<Session>(await g8Post("/agent/sessions", {})).id ?? null, { onSuccess: (id) => { list.reload(); if (id) { setOpenId(id); setReply(null); } } });
+  const rename = useG8Mutation((v: { id: string; title: string }) => g8Post(`/agent/sessions/${enc(v.id)}/rename`, { title: v.title }), { onSuccess: () => { setRenaming(null); list.reload(); } });
+  const pin = useG8Mutation((v: { id: string; pinned: boolean }) => g8Post(`/agent/sessions/${enc(v.id)}/pin`, { is_pinned: v.pinned }), { onSuccess: () => list.reload() });
+  const remove = useG8Mutation((id: string) => g8Delete(`/agent/sessions/${enc(id)}`), { onSuccess: (_r, id) => { setDeleting(null); if (openId === id) setOpenId(null); list.reload(); }, onError: () => setDeleting(null) });
+  const note = useG8Mutation((v: { id: string; content: string }) => g8Post(`/agent/sessions/${enc(v.id)}/messages`, { content: v.content }), { onSuccess: () => { setDraft(""); setTurn((t) => t + 1); } });
+  // One id per turn, reused when the same turn is retried, so a retry after a timeout cannot be charged twice (the API dedupes on it within a session).
+  const turn = useRef<{ id: string; text: string } | null>(null);
+  const ask = useG8Mutation(async (message: string) => {
+    if (turn.current?.text !== message) turn.current = { id: globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`, text: message };
+    return bodyOf<{ message?: string; kind?: string; work_item_id?: string; session_id?: string }>(await g8Post("/agent/chat", { message, ...(openId ? { session_id: openId, client_turn_id: turn.current.id } : {}) }));
+  },
+    { onSuccess: (r) => { turn.current = null; setAsking(null); setDraft(""); setReply(r); setTurn((t) => t + 1); list.reload(); if (!openId && (r as { session_id?: string }).session_id) setOpenId((r as { session_id?: string }).session_id ?? null); }, onError: () => setAsking(null) });
+
+  return (
+    <div className={`grid gap-4 lg:grid-cols-[18rem_1fr] ${className ?? ""}`}>
+      <div className="flex flex-col gap-2">
+        <div className="flex items-center justify-between"><h3 className="text-sm font-medium">Sessions</h3><Button size="sm" variant="outline" loading={create.loading} onClick={() => void create.mutate(undefined)}>New session</Button></div>
+        {list.error ? <ApiError error={list.error} title="Could not load sessions" onRetry={list.reload} /> : null}
+        {list.loading ? <Skeleton className="h-16 w-full" aria-label="Loading sessions" /> : null}
+        <ul className="divide-y rounded-md border">
+          {rows.map((s) => (
+            <li key={s.id} className={s.id === openId ? "bg-accent" : ""}>
+              <button type="button" data-testid={`session-${s.id}`} className="flex w-full items-center gap-2 px-3 py-2 text-left text-sm" onClick={() => { setOpenId(s.id ?? null); setReply(null); setRenaming(null); }}>
+                {s.is_pinned ? <Pin className="size-3.5 shrink-0" aria-label="Pinned" /> : null}
+                <span className="min-w-0"><span className="block truncate font-medium">{s.title || "Untitled session"}</span><span className="block text-xs text-muted-foreground">{s.updated_at ? new Date(s.updated_at).toLocaleString() : ""}</span></span>
+              </button>
+            </li>
+          ))}
+        </ul>
+        {!list.loading && !list.error && rows.length === 0 ? <EmptyState compact icon={<MessagesSquare strokeWidth={1.5} />} title="No sessions yet" description="Ask the assistant something to start one." /> : null}
+        <LoadMore list={list} noun="sessions" />
+        {create.error ? <ApiError error={create.error} title="Could not start a session" /> : null}
+      </div>
+      <div className="flex min-w-0 flex-col gap-3">
+        {open?.id ? (
+          <>
+            <div className="flex flex-wrap items-center gap-2">
+              {renaming === open.id ? (
+                <><Input aria-label="Session title" className="max-w-xs" value={title} onChange={(e) => setTitle(e.target.value)} /><Button size="sm" loading={rename.loading} disabled={!title.trim()} onClick={() => void rename.mutate({ id: open.id as string, title: title.trim() })}>Save title</Button><Button size="sm" variant="ghost" onClick={() => setRenaming(null)}>Cancel</Button></>
+              ) : (
+                <><h3 className="text-sm font-medium">{open.title || "Untitled session"}</h3><Button size="sm" variant="outline" onClick={() => { setTitle(open.title ?? ""); setRenaming(open.id ?? null); }}>Rename</Button>
+                  <Button size="sm" variant="outline" loading={pin.loading} onClick={() => void pin.mutate({ id: open.id as string, pinned: !open.is_pinned })}>{open.is_pinned ? "Unpin" : "Pin"}</Button><Button size="sm" variant="ghost" onClick={() => setDeleting(open)}>Delete</Button></>
+              )}
+            </div>
+            {rename.error ? <ApiError error={rename.error} title="Could not rename the session" /> : null}
+            {pin.error ? <ApiError error={pin.error} title="Could not pin the session" /> : null}
+            <Transcript sessionId={open.id} refreshKey={turnKey} />
+          </>
+        ) : <p className="text-sm text-muted-foreground">Pick a session, or ask below to start a new one.</p>}
+        {reply?.message ? <p role="status" className="rounded-md border bg-accent px-3 py-2 text-sm" data-testid="assistant-reply">{reply.message}</p> : null}
+        {reply?.kind === "work_item" && reply.work_item_id ? <p role="status" className="text-sm">The assistant started a run. {onOpenRun ? <button type="button" className="underline" onClick={() => onOpenRun(reply.work_item_id as string)}>Open the run</button> : <span className="text-muted-foreground">Follow it on the Runs tab ({reply.work_item_id}).</span>}</p> : null}
+        <div className="flex flex-col gap-2 border-t pt-3">
+          <Textarea aria-label="Message to the assistant" rows={3} value={draft} onChange={(e) => setDraft(e.target.value)} placeholder="Ask the assistant, or leave it a note" />
+          {ask.error ? <ApiError error={ask.error} title="The assistant could not answer" /> : null}
+          {note.error ? <ApiError error={note.error} title="Could not add the note" /> : null}
+          <div className="flex justify-end gap-2">
+            <Button variant="outline" loading={note.loading} disabled={!draft.trim() || !open?.id} onClick={() => open?.id && void note.mutate({ id: open.id, content: draft.trim() })}>Add a note</Button>
+            <Button disabled={!draft.trim()} onClick={() => setAsking(draft.trim())}>Ask</Button>
+          </div>
+        </div>
+      </div>
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the session" /> : null}
+      <ConfirmSpendDialog open={asking != null} tier="billable" title="Ask the assistant" description="The assistant runs a model for this turn and charges for it. If it reads your message as a job, it starts a run that works on its own and spends credits as it goes."
+        confirmLabel="Ask" confirming={ask.loading} onConfirm={() => asking && void ask.mutate(asking)} onCancel={() => setAsking(null)} />
+      <ConfirmSpendDialog open={deleting != null} tier="destructive" title={`Delete "${deleting?.title || "this session"}"`} description="The conversation and its history are removed." affected={1}
+        confirmLabel="Delete" confirming={remove.loading} onConfirm={() => deleting?.id && void remove.mutate(deleting.id)} onCancel={() => setDeleting(null)} />
+    </div>
+  );
+}

package/blocks/agents/components/duplicate-agent-button.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+/**
+ * DuplicateAgentButton: copy an agent under a new name. The copy keeps the persona, voice, knowledge and skills and is a separate agent
+ * from then on. The copy is made once: if the dialog is retried after a failure, the id of the copy already made is reused.
+ *
+ * SDK operations:
+ *   cloneAgent   POST /voice/agents/clone { source_agent_id, new_agent_name }   (write)
+ */
+import { useRef, 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 { agentIdOf } from "../lib/agent-types";
+import type { AgentSummary } from "../lib/agent-types";
+import { NameDialog } from "./name-dialog";
+
+export interface DuplicateAgentButtonProps {
+  agent: Pick<AgentSummary, "agent_id" | "agent_name">;
+  /** Called with the id of the new agent. */
+  onDuplicated?: (agentId: string) => void;
+  variant?: "outline" | "ghost";
+}
+
+export function DuplicateAgentButton({ agent, onDuplicated, variant = "outline" }: DuplicateAgentButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [name, setName] = useState("");
+  const made = useRef<string | null>(null);
+  const clone = useG8Mutation(async (n: string) => {
+    if (made.current) return made.current;
+    const id = agentIdOf(await g8Post("/voice/agents/clone", { source_agent_id: agent.agent_id, new_agent_name: n }));
+    made.current = id || null;
+    return id;
+  }, { onSuccess: (id) => { made.current = null; setOpen(false); if (id) onDuplicated?.(id); } });
+  return (
+    <>
+      <Button size="sm" variant={variant} onClick={() => { made.current = null; clone.reset(); setName(`Copy of ${agent.agent_name}`); setOpen(true); }}>Duplicate</Button>
+      <NameDialog open={open} title={`Duplicate ${agent.agent_name}`} description="The copy keeps the persona, voice, knowledge and skills. It is a separate agent from now on." label="Name of the copy"
+        value={name} onChange={setName} confirm="Duplicate" busy={clone.loading} error={clone.error} onCancel={() => setOpen(false)} onConfirm={() => void clone.mutate(name.trim())} />
+    </>
+  );
+}

package/blocks/agents/components/from-template-button.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+/**
+ * FromTemplateButton: start a new agent from a graph8 or workspace template. Pick a template, name the agent, and it is created as a copy
+ * (adjust it afterwards). The copy is made once: a retry after a failure reuses the id of the copy already made.
+ *
+ * SDK operations, in order:
+ *   1. listAgentTemplates   GET  /voice/agent-templates?entity_type=agent&include_system_templates=true   (read)
+ *   2. cloneAgent           POST /voice/agents/clone { source_agent_id, new_agent_name }                   (write)
+ */
+import { useRef, useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+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 { agentIdOf, listOf } from "../lib/agent-types";
+
+export interface FromTemplateButtonProps {
+  /** Called with the id of the new agent. */
+  onCreated?: (agentId: string) => void;
+}
+
+interface Template { agent_id: string; agent_name: string; role?: string; description?: string | null }
+
+export function FromTemplateButton({ onCreated }: FromTemplateButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [picked, setPicked] = useState<Template | null>(null);
+  const [name, setName] = useState("");
+  const made = useRef<string | null>(null);
+  const templates = useG8Query((signal) => g8Get("/voice/agent-templates", { entity_type: "agent", include_system_templates: true }, { signal }), [], { enabled: open });
+  const create = useG8Mutation(async (v: { source: string; name: string }) => {
+    if (made.current) return made.current;
+    const id = agentIdOf(await g8Post("/voice/agents/clone", { source_agent_id: v.source, new_agent_name: v.name }));
+    made.current = id || null;
+    return id;
+  }, { onSuccess: (id) => { made.current = null; setOpen(false); setPicked(null); if (id) onCreated?.(id); } });
+  const rows = listOf<Template>(templates.data, "templates", "items");
+  return (
+    <>
+      <Button variant="outline" onClick={() => { made.current = null; create.reset(); setOpen(true); }}>From a template</Button>
+      <Dialog open={open} onOpenChange={(o) => !o && !create.loading && setOpen(false)}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>Start from a template</DialogTitle><DialogDescription>Pick a template, name your agent, and adjust 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={t.agent_id}>
+                <button type="button" aria-pressed={picked?.agent_id === t.agent_id} className={`block w-full px-3 py-2 text-left text-sm ${picked?.agent_id === t.agent_id ? "bg-accent" : ""}`} onClick={() => { setPicked(t); setName(t.agent_name); }}>
+                  <span className="font-medium">{t.agent_name}</span>{t.role ? <span className="ml-2 text-xs text-muted-foreground">{t.role}</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">No templates yet. Save an agent as a template first.</p> : null}
+          {picked ? <div className="flex flex-col gap-1"><Label htmlFor="template-agent-name">Name of the new agent</Label><Input id="template-agent-name" value={name} onChange={(e) => setName(e.target.value)} /></div> : null}
+          {create.error ? <ApiError error={create.error} title="Could not create the agent" /> : null}
+          <DialogFooter><Button variant="ghost" disabled={create.loading} onClick={() => setOpen(false)}>Cancel</Button><Button loading={create.loading} disabled={!picked || !name.trim()} onClick={() => picked && void create.mutate({ source: picked.agent_id, name: name.trim() })}>Create agent</Button></DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

package/blocks/agents/components/knowledge-browser.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+/**
+ * KnowledgeBrowser: the company knowledge agents draw on. A status strip (entries, how many are draft, stable or deprecated, sync state),
+ * search (meaning-based, with an excerpt) or browse (filter by type and lifecycle), the list, and the open entry in a side panel
+ * (KnowledgeDetail, deep link ?concept=). "New entry" writes one (KnowledgeForm). "Export" downloads everything as a single archive.
+ * The list loads 25 at a time and "Load more" asks the API for more, up to its maximum of 100; at the maximum it says so.
+ *
+ * SDK operations, in order:
+ *   1. getKnowledgeStatus  GET /knowledge/status                        (read)
+ *   2. listKnowledge       GET /knowledge?concept_type&lifecycle&limit   (read)
+ *   3. searchKnowledge     GET /knowledge/search?query&limit=50          (read)  when the search box has text
+ *   4. exportKnowledge     GET /knowledge/export                         (read)  a link to the archive (opened in a new tab)
+ *   5. KnowledgeDetail / KnowledgeForm  see their files (get, history, sources, related, author, verify, deprecate)
+ */
+import { useMemo, useState } from "react";
+import { BookOpen, Plus } from "lucide-react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import { LIFECYCLES } from "../lib/knowledge-utils";
+import type { KnowledgeSummary } from "../lib/knowledge-utils";
+import { LoadMore, useGrowingList } from "../lib/load-more";
+import { KnowledgeDetail } from "./knowledge-detail";
+import { KnowledgeForm } from "./knowledge-form";
+
+export interface KnowledgeBrowserProps {
+  className?: string;
+}
+
+interface Hit { summary?: KnowledgeSummary; excerpt?: string }
+interface Status { concept_count?: number; counts_by_lifecycle?: Record<string, number>; sync_state?: string; capabilities?: Record<string, boolean> }
+
+// A constant: the form resets its draft when `mode` changes identity, so it must not be rebuilt on every render.
+const NEW_MODE = { kind: "new" } as const;
+
+export function KnowledgeBrowser({ className }: KnowledgeBrowserProps) {
+  const [open, setOpen] = useUrlState("concept", "");
+  const [view, setView] = useUrlState("view", "");
+  const [search, setSearch] = useState("");
+  const [type, setType] = useState("");
+  const [lifecycle, setLifecycle] = useState("");
+  const [creating, setCreating] = useState(false);
+  const q = search.trim();
+  const status = useG8Query((signal) => g8Get("/knowledge/status", undefined, { signal }), []);
+  const list = useGrowingList<KnowledgeSummary>(async (limit, signal) => listOf<KnowledgeSummary>(await g8Get("/knowledge", { concept_type: type.trim() || undefined, lifecycle: lifecycle || undefined, limit }, { signal }), "items", "concepts"), [type, lifecycle], { pageSize: 25, max: 100, enabled: !q });
+  const hits = useG8Query((signal) => g8Get("/knowledge/search", { query: q, limit: 50 }, { signal }), [q], { enabled: Boolean(q) });
+  const st = bodyOf<Status>(status.data);
+  const lc = st.counts_by_lifecycle ?? {};
+  const rows: Array<{ s: KnowledgeSummary; excerpt?: string }> = useMemo(() => q
+    ? listOf<Hit>(hits.data).filter((h) => h.summary).map((h) => ({ s: h.summary as KnowledgeSummary, excerpt: h.excerpt }))
+    : list.items.map((s) => ({ s })), [q, hits.data, list.items]);
+  const types = useMemo(() => [...new Set(list.items.map((s) => s.concept_type).filter(Boolean))], [list.items]);
+  const loading = q ? hits.loading && !hits.data : list.loading;
+  const error = q ? hits.error : list.error;
+  const expanded = view === "full" && Boolean(open);
+  const refresh = () => { void status.refetch(); list.reload(); };
+
+  const listing = (
+    <div className="flex flex-col gap-3">
+      <Toolbar search={{ value: search, onChange: setSearch, placeholder: "Search company knowledge" }}
+        filters={q ? undefined : <><Input aria-label="Filter by type" placeholder="Any type" list="kn-filter-types" className="h-8 w-36" value={type} onChange={(e) => setType(e.target.value)} />
+          <datalist id="kn-filter-types">{types.map((t) => <option key={t} value={t} />)}</datalist>
+          <select aria-label="Lifecycle" className="h-8 rounded-md border bg-background px-2 text-sm" value={lifecycle} onChange={(e) => setLifecycle(e.target.value)}><option value="">Any state</option>{LIFECYCLES.map((l) => <option key={l} value={l}>{l}</option>)}</select></>}
+        actions={<><Button size="sm" variant="outline" asChild><a href="/api/g8/knowledge/export" target="_blank" rel="noreferrer">Export</a></Button><Button size="sm" onClick={() => setCreating(true)}><Plus className="mr-1 size-4" />New entry</Button></>} />
+      {error ? <ApiError error={error} title="Could not load company knowledge" onRetry={() => (q ? void hits.refetch() : list.reload())} /> : null}
+      {loading ? <p className="text-sm text-muted-foreground" aria-busy="true">Loading knowledge...</p> : null}
+      <ul className="divide-y rounded-md border">
+        {rows.map(({ s, excerpt }) => (
+          <li key={s.concept_id} className={open === s.concept_id ? "bg-accent" : ""}>
+            <button type="button" data-testid={`concept-${s.concept_id}`} className="flex w-full items-start justify-between gap-3 px-3 py-2 text-left text-sm" onClick={() => setOpen(s.concept_id)}>
+              <span className="min-w-0"><span className="block truncate font-medium">{s.title}</span><span className="block truncate text-xs text-muted-foreground">{excerpt || s.logical_path || s.concept_type}</span></span>
+              <span className="flex shrink-0 items-center gap-1.5"><span className="text-xs text-muted-foreground">{s.concept_type}</span><StatusPill tone={toneForStatus(s.knowledge_status)} dot>{s.knowledge_status ?? "unknown"}</StatusPill></span>
+            </button>
+          </li>
+        ))}
+      </ul>
+      {!loading && !error && rows.length === 0 ? <EmptyState icon={<BookOpen strokeWidth={1.5} />} title={q ? "Nothing matches" : "No knowledge yet"} description={q ? "Try other words." : "Write down how your company sells, prices and supports, so agents can use it."} action={q ? undefined : <Button onClick={() => setCreating(true)}>New entry</Button>} /> : null}
+      {q && rows.length >= 50 ? <p className="text-center text-xs text-muted-foreground">Showing the 50 best matches. Narrow the search to see others.</p> : null}
+      {!q ? <LoadMore list={list} noun="entries" /> : null}
+    </div>
+  );
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <StatStrip loading={status.loading && !status.data} items={status.error ? [] : [
+        { label: "Entries", value: String(st.concept_count ?? 0) },
+        { label: "Stable", value: String(lc.stable ?? 0), tone: "positive" },
+        { label: "Draft", value: String(lc.draft ?? 0), tone: "warning" },
+        { label: "Deprecated", value: String(lc.deprecated ?? 0) },
+        { label: "Sync", value: st.sync_state ?? "unknown" },
+      ]} />
+      {status.error ? <ApiError compact error={status.error} title="Could not load the knowledge status" onRetry={() => void status.refetch()} /> : null}
+      <SplitView list={listing} detailOpen={Boolean(open)} onCloseDetail={() => { setOpen(""); setView(""); }} expanded={expanded} onExpandedChange={(e) => setView(e ? "full" : "")} detailWidth="xl"
+        detail={open ? <KnowledgeDetail key={open} conceptId={open} onClose={() => { setOpen(""); setView(""); }} onExpand={expanded ? undefined : () => setView("full")} onCollapse={expanded ? () => setView("") : undefined} onOpenConcept={setOpen} onChanged={refresh} /> : null} />
+      <KnowledgeForm mode={creating ? NEW_MODE : null} typeSuggestions={types} onClose={() => setCreating(false)} onSaved={(id) => { refresh(); if (id) setOpen(id); }} />
+    </div>
+  );
+}

package/blocks/agents/components/knowledge-detail.tsx

@@ -0,0 +1,156 @@
+"use client";
+
+/**
+ * KnowledgeDetail: one company knowledge entry in full. Tabs: Content (the Markdown, warnings), History (every version and amendment, newest
+ * first, "Load more" follows the cursor), Sources (what it was written from) and Related (linked entries, which open in place).
+ * Actions for authored entries (generated ones come from your CRM and campaigns and are read only):
+ *   Edit draft / Propose new version (KnowledgeForm), Verify (approve or reject, with the authority that signs off), Deprecate (a reason, optionally
+ *   the entry that replaces it; destructive, confirmed).
+ *
+ * SDK operations, in order:
+ *   1. getKnowledge                 GET  /knowledge/{concept_id}                 (read)
+ *   2. getKnowledgeHistory          GET  /knowledge/{concept_id}/history?cursor&limit   (read)
+ *   3. knowledgeSources             GET  /knowledge/{concept_id}/sources          (read)
+ *   4. relatedKnowledge             GET  /knowledge/{concept_id}/related?depth=1&limit=20   (read)
+ *   5. verifyAuthoredKnowledge      POST /knowledge/authored/{concept_id}/verify { approve, authority }   (write)
+ *   6. deprecateAuthoredKnowledge   POST /knowledge/authored/{concept_id}/deprecate { reason, superseded_by? }   (destructive, ConfirmSpendDialog)
+ *   7. KnowledgeForm: create/update draft/amend (see knowledge-form.tsx)
+ */
+import { useEffect, useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import { bodyFromMarkdown, conceptOf, isAuthored } from "../lib/knowledge-utils";
+import { KnowledgeForm } from "./knowledge-form";
+import type { KnowledgeFormMode } from "./knowledge-form";
+
+export interface KnowledgeDetailProps {
+  conceptId: string;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  /** Open another entry (from Related). */
+  onOpenConcept?: (conceptId: string) => void;
+  /** After any change, so the host can refresh its list. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+type Row = Record<string, unknown>;
+const str = (v: unknown): string => (typeof v === "string" ? v : typeof v === "number" ? String(v) : "");
+
+function History({ conceptId }: { conceptId: string }) {
+  const [rows, setRows] = useState<Row[]>([]);
+  const [cursor, setCursor] = useState<string | undefined>();
+  const [next, setNext] = useState<string | undefined>();
+  const q = useG8Query((signal) => g8Get(`/knowledge/${encodeURIComponent(conceptId)}/history`, { limit: 25, cursor }, { signal }), [conceptId, cursor]);
+  useEffect(() => { setRows([]); setCursor(undefined); setNext(undefined); }, [conceptId]);
+  useEffect(() => {
+    if (!q.data) return;
+    const page = listOf<Row>(q.data, "items", "versions", "revisions", "history");
+    setRows((prev) => (cursor ? [...prev, ...page] : page));
+    const body = bodyOf<{ next_cursor?: string | null }>(q.data);
+    setNext(body.next_cursor ?? (q.data as { pagination?: { next_cursor?: string | null } }).pagination?.next_cursor ?? undefined);
+  }, [q.data]); // eslint-disable-line react-hooks/exhaustive-deps
+  if (q.error) return <ApiError error={q.error} title="Could not load the history" onRetry={() => void q.refetch()} />;
+  if (q.loading && rows.length === 0) return <Skeleton className="h-16 w-full" />;
+  if (rows.length === 0) return <p className="text-sm text-muted-foreground">No revisions recorded.</p>;
+  return (
+    <div className="flex flex-col gap-2">
+      <ul className="divide-y rounded-md border" aria-label="Revisions">
+        {rows.map((r, i) => (
+          <li key={i} className="flex flex-wrap items-center justify-between gap-2 px-3 py-2 text-sm">
+            <span>{str(r.summary ?? r.title ?? r.change ?? r.action ?? r.version ?? r.revision) || `Revision ${rows.length - i}`}<span className="block text-xs text-muted-foreground">{str(r.actor ?? r.author ?? r.actor_id)}</span></span>
+            <span className="flex items-center gap-2">{str(r.knowledge_status ?? r.status) ? <StatusPill tone={toneForStatus(str(r.knowledge_status ?? r.status))}>{str(r.knowledge_status ?? r.status)}</StatusPill> : null}<span className="text-xs text-muted-foreground">{str(r.created_at ?? r.at ?? r.recorded_at) ? new Date(str(r.created_at ?? r.at ?? r.recorded_at)).toLocaleString() : ""}</span></span>
+          </li>
+        ))}
+      </ul>
+      {next ? <Button size="sm" variant="outline" className="self-center" loading={q.loading} onClick={() => setCursor(next)}>Load more revisions</Button> : null}
+    </div>
+  );
+}
+
+export function KnowledgeDetail({ conceptId, onClose, onExpand, onCollapse, onOpenConcept, onChanged, className }: KnowledgeDetailProps) {
+  const [form, setForm] = useState<KnowledgeFormMode | null>(null);
+  const [verifying, setVerifying] = useState<{ approve: boolean; authority: string } | null>(null);
+  const [deprecating, setDeprecating] = useState<{ reason: string; superseded_by: string } | null>(null);
+  const [confirmDeprecate, setConfirmDeprecate] = useState(false);
+  useEffect(() => { setForm(null); setVerifying(null); setDeprecating(null); setConfirmDeprecate(false); }, [conceptId]);
+  const enc = encodeURIComponent(conceptId);
+  const concept = useG8Query((signal) => g8Get(`/knowledge/${enc}`, undefined, { signal }), [conceptId]);
+  const sources = useG8Query((signal) => g8Get(`/knowledge/${enc}/sources`, undefined, { signal }), [conceptId]);
+  const related = useG8Query((signal) => g8Get(`/knowledge/${enc}/related`, { depth: 1, limit: 20 }, { signal }), [conceptId]);
+  const c = conceptOf(concept.data);
+  const done = () => { void concept.refetch(); onChanged?.(); };
+  const verify = useG8Mutation((v: { approve: boolean; authority: string }) => g8Post(`/knowledge/authored/${enc}/verify`, v), { onSuccess: () => { setVerifying(null); done(); } });
+  const deprecate = useG8Mutation((v: { reason: string; superseded_by: string }) => g8Post(`/knowledge/authored/${enc}/deprecate`, { reason: v.reason, ...(v.superseded_by ? { superseded_by: v.superseded_by } : {}) }), { onSuccess: () => { setConfirmDeprecate(false); setDeprecating(null); done(); }, onError: () => setConfirmDeprecate(false) });
+
+  if (concept.error) return <ApiError error={concept.error} title="Could not load the entry" onRetry={() => void concept.refetch()} />;
+  if (!c) return <Skeleton className="h-40 w-full" aria-label="Loading entry" />;
+  const s = c.summary;
+  const authored = isAuthored(s);
+  const status = s.knowledge_status ?? "";
+  const loaded = { title: s.title, concept_type: s.concept_type, body: bodyFromMarkdown(c.markdown) };
+  const srcRows = listOf<{ resource?: string; title?: string | null; locator?: string | null }>(sources.data);
+  const relRows = listOf<{ concept_id?: string; title?: string; concept_type?: string; summary?: { concept_id?: string; title?: string } }>(related.data);
+
+  const actions = authored ? (
+    <>
+      {status === "draft" ? <Button size="sm" variant="outline" onClick={() => setForm({ kind: "edit", conceptId, loaded })}>Edit draft</Button> : null}
+      {status === "stable" ? <Button size="sm" variant="outline" onClick={() => setForm({ kind: "amend", conceptId, loaded })}>Propose new version</Button> : null}
+      {status !== "deprecated" ? <Button size="sm" variant="outline" onClick={() => setVerifying({ approve: true, authority: "" })}>Verify</Button> : null}
+      {status !== "deprecated" ? <Button size="sm" variant="ghost" onClick={() => setDeprecating({ reason: "", superseded_by: "" })}>Deprecate</Button> : null}
+    </>
+  ) : undefined;
+
+  return (
+    <>
+      <DetailPanel className={className} title={s.title} subtitle={s.logical_path ?? s.concept_type} onClose={onClose} onExpand={onExpand} onCollapse={onCollapse} actions={actions}
+        badges={<><StatusPill tone={toneForStatus(status)} dot>{status || "unknown"}</StatusPill>{s.trust_tier ? <StatusPill tone="neutral">{s.trust_tier.replace(/_/g, " ")}</StatusPill> : null}{s.stale ? <StatusPill tone="warning">stale</StatusPill> : null}{!authored ? <StatusPill tone="info" title="Built from your records; change the source, not the entry">generated</StatusPill> : null}</>}
+        tabs={[
+          { id: "content", label: "Content", content: (
+            <div className="flex flex-col gap-3">
+              {(c.warnings ?? []).map((w) => <p key={w} role="status" className="rounded-md border border-warning-foreground/25 bg-warning p-2 text-sm text-warning-foreground">{w}</p>)}
+              <pre className="whitespace-pre-wrap text-sm">{bodyFromMarkdown(c.markdown) || "This entry has no content."}</pre>
+            </div>) },
+          { id: "history", label: "History", content: <History conceptId={conceptId} /> },
+          { id: "sources", label: "Sources", count: srcRows.length, content: sources.error ? <ApiError error={sources.error} title="Could not load the sources" onRetry={() => void sources.refetch()} /> : srcRows.length === 0 ? <p className="text-sm text-muted-foreground">No sources recorded.</p> : (
+            <ul className="divide-y rounded-md border">{srcRows.map((r, i) => <li key={i} className="px-3 py-2 text-sm">{r.title || r.resource}{r.locator ? <span className="block text-xs text-muted-foreground">{r.locator}</span> : null}</li>)}</ul>) },
+          { id: "related", label: "Related", count: relRows.length, content: related.error ? <ApiError error={related.error} title="Could not load related entries" onRetry={() => void related.refetch()} /> : relRows.length === 0 ? <p className="text-sm text-muted-foreground">Nothing linked yet.</p> : (
+            <ul className="divide-y rounded-md border">{relRows.map((r, i) => { const id = r.concept_id ?? r.summary?.concept_id ?? ""; const title = r.title ?? r.summary?.title ?? id; return <li key={id || i}><button type="button" className="w-full px-3 py-2 text-left text-sm hover:bg-accent" disabled={!id || !onOpenConcept} onClick={() => onOpenConcept?.(id)}>{title}{r.concept_type ? <span className="ml-2 text-xs text-muted-foreground">{r.concept_type}</span> : null}</button></li>; })}</ul>) },
+        ]}>
+        {null}
+      </DetailPanel>
+      <KnowledgeForm mode={form} onClose={() => setForm(null)} onSaved={() => done()} />
+      <Dialog open={verifying != null} onOpenChange={(o) => !o && setVerifying(null)}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>Verify this entry</DialogTitle><DialogDescription>Say who signs it off. Approved entries are trusted more by agents.</DialogDescription></DialogHeader>
+          <div className="flex flex-col gap-1"><Label htmlFor="kn-authority">Authority</Label><Input id="kn-authority" placeholder="Head of Sales" value={verifying?.authority ?? ""} onChange={(e) => setVerifying((v) => v && { ...v, authority: e.target.value })} /></div>
+          {verify.error ? <ApiError error={verify.error} title="Could not record the decision" /> : null}
+          <DialogFooter>
+            <Button variant="ghost" onClick={() => setVerifying(null)}>Cancel</Button>
+            <Button variant="outline" loading={verify.loading} disabled={!verifying?.authority.trim()} onClick={() => verifying && void verify.mutate({ approve: false, authority: verifying.authority.trim() })}>Reject</Button>
+            <Button loading={verify.loading} disabled={!verifying?.authority.trim()} onClick={() => verifying && void verify.mutate({ approve: true, authority: verifying.authority.trim() })}>Approve</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <Dialog open={deprecating != null && !confirmDeprecate} onOpenChange={(o) => !o && setDeprecating(null)}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>Deprecate this entry</DialogTitle><DialogDescription>Agents stop relying on it. The history is kept.</DialogDescription></DialogHeader>
+          <div className="flex flex-col gap-1"><Label htmlFor="kn-reason">Reason</Label><Input id="kn-reason" value={deprecating?.reason ?? ""} onChange={(e) => setDeprecating((v) => v && { ...v, reason: e.target.value })} /></div>
+          <div className="flex flex-col gap-1"><Label htmlFor="kn-superseded">Replaced by (entry id, optional)</Label><Input id="kn-superseded" value={deprecating?.superseded_by ?? ""} onChange={(e) => setDeprecating((v) => v && { ...v, superseded_by: e.target.value })} /></div>
+          {deprecate.error ? <ApiError error={deprecate.error} title="Could not deprecate the entry" /> : null}
+          <DialogFooter><Button variant="ghost" onClick={() => setDeprecating(null)}>Cancel</Button><Button disabled={!deprecating?.reason.trim()} onClick={() => setConfirmDeprecate(true)}>Continue</Button></DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <ConfirmSpendDialog open={confirmDeprecate} tier="destructive" title={`Deprecate "${s.title}"`} description="Agents stop relying on this entry. It stays in the history, but cannot be made current again." affected={1}
+        confirmLabel="Deprecate" confirming={deprecate.loading} onConfirm={() => deprecating && void deprecate.mutate(deprecating)} onCancel={() => setConfirmDeprecate(false)} />
+    </>
+  );
+}

package/blocks/agents/components/knowledge-form.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+/**
+ * KnowledgeForm: write a company knowledge entry in a side sheet.
+ *   mode "new"    a new draft entry (createAuthoredKnowledge).
+ *   mode "edit"   change a DRAFT entry in place (updateAuthoredKnowledgeDraft).
+ *   mode "amend"  propose a new version of a published entry (createAuthoredKnowledgeAmendment); it is reviewed before it replaces the old one.
+ * The API takes the whole entry, so edit and amend start from the LOADED entry and stay disabled until it has loaded; Save is only
+ * enabled when something changed. Nothing here spends credits or reaches outside the workspace.
+ *
+ * SDK operations:
+ *   createAuthoredKnowledge            POST  /knowledge/authored { title, concept_type, body }                    (write)
+ *   updateAuthoredKnowledgeDraft       PATCH /knowledge/authored/{concept_id} { title, concept_type, body }       (write)
+ *   createAuthoredKnowledgeAmendment   POST  /knowledge/authored/{concept_id}/amendments { title, concept_type, body }   (write)
+ */
+import { useEffect, useState } from "react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { bodyOf } from "../lib/agent-types";
+import type { KnowledgeInput } from "../lib/knowledge-utils";
+
+export type KnowledgeFormMode = { kind: "new" } | { kind: "edit"; conceptId: string; loaded: KnowledgeInput } | { kind: "amend"; conceptId: string; loaded: KnowledgeInput };
+
+export interface KnowledgeFormProps {
+  mode: KnowledgeFormMode | null;
+  /** Types already in use, offered as suggestions. */
+  typeSuggestions?: string[];
+  onClose: () => void;
+  onSaved?: (conceptId: string | undefined) => void;
+}
+
+const BLANK: KnowledgeInput = { title: "", concept_type: "", body: "" };
+const COPY = { new: ["New knowledge entry", "Create entry"], edit: ["Edit draft", "Save draft"], amend: ["Propose a new version", "Propose version"] } as const;
+
+export function KnowledgeForm({ mode, typeSuggestions = [], onClose, onSaved }: KnowledgeFormProps) {
+  const [d, setD] = useState<KnowledgeInput>(BLANK);
+  const seed = mode && mode.kind !== "new" ? mode.loaded : BLANK;
+  useEffect(() => { setD(mode && mode.kind !== "new" ? mode.loaded : BLANK); }, [mode]);
+  const save = useG8Mutation(async () => {
+    if (!mode) return undefined;
+    const res = mode.kind === "new" ? await g8Post("/knowledge/authored", d)
+      : mode.kind === "edit" ? await g8Patch(`/knowledge/authored/${encodeURIComponent(mode.conceptId)}`, d)
+      : await g8Post(`/knowledge/authored/${encodeURIComponent(mode.conceptId)}/amendments`, d);
+    return bodyOf<{ concept_id?: string }>(res).concept_id;
+  }, { onSuccess: (id) => { onSaved?.(id); onClose(); } });
+  const set = (patch: Partial<KnowledgeInput>) => setD((x) => ({ ...x, ...patch }));
+  const changed = d.title !== seed.title || d.concept_type !== seed.concept_type || d.body !== seed.body;
+  const valid = d.title.trim() && d.concept_type.trim() && d.body.trim();
+  const [title, cta] = COPY[mode?.kind ?? "new"];
+  return (
+    <FormSheet open={mode != null} onOpenChange={(o) => !o && onClose()} title={title} width="xl"
+      description={mode?.kind === "amend" ? "The new version is reviewed before it replaces the published one." : "Written in Markdown. Agents can draw on it once it is published."}
+      footer={<><Button variant="ghost" onClick={onClose}>Cancel</Button><Button loading={save.loading} disabled={!valid || !changed} onClick={() => void save.mutate(undefined)}>{cta}</Button></>}>
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-col gap-1"><Label htmlFor="kn-title">Title</Label><Input id="kn-title" value={d.title} onChange={(e) => set({ title: e.target.value })} /></div>
+        <div className="flex flex-col gap-1">
+          <Label htmlFor="kn-type">Type</Label>
+          <Input id="kn-type" list="kn-types" placeholder="playbook, policy, faq" value={d.concept_type} onChange={(e) => set({ concept_type: e.target.value })} />
+          <datalist id="kn-types">{typeSuggestions.map((t) => <option key={t} value={t} />)}</datalist>
+        </div>
+        <div className="flex flex-col gap-1"><Label htmlFor="kn-body">Content (Markdown)</Label><Textarea id="kn-body" rows={14} className="font-mono text-xs" value={d.body} onChange={(e) => set({ body: e.target.value })} /></div>
+        {save.error ? <ApiError error={save.error} title="Could not save the entry" /> : null}
+      </div>
+    </FormSheet>
+  );
+}