@graph8/sdk 0.370.0 → 0.374.0

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

@@ -15,13 +15,23 @@
  * renders its own ScreenLayout header ("Inbox" h1, stats). Opt out with `urlState={false}` (selection kept in component
  * state, the URL untouched) and/or `hideHeader` (no title or stats, just the toolbar and the two panes). Defaults keep the new look.
  *
+ * Management (all optional, on by default; `showManagement={false}` hides the three toolbar buttons):
+ *   - "New message" (ComposeMessage): write a new email or text from a sender you choose (external, confirmed).
+ *   - "Search all" (InboxSearch): search every email thread or LinkedIn conversation on the server, then open a result.
+ *   - "Manage" (TagManager + BlockedSenders): create, rename, delete tags; block and unblock senders. The tag list it
+ *     loads also feeds the tag filter and the tag picker.
+ *   - In an open conversation, with `showThreadActions` (default off), "Manage conversation" (ThreadActions): mark read or unread, remove a tag, unassign, block sender.
+ * SDK operations of its own: none; the parts above own theirs and their confirm dialogs.
+ * A conversation this key cannot see (or that was removed) answers 404; the conversation view says so instead of failing.
+ *
  * Props are backwards compatible: `initialFilters`, `availableTags`, `className` as before; everything else is optional glue.
  */
 import { useMemo, useState, type ReactNode } from "react";
-import { Inbox as InboxIcon, Mail, RefreshCw } from "lucide-react";
+import { Inbox as InboxIcon, Mail, PenSquare, RefreshCw, Search, Tags } from "lucide-react";
 import { Button, Skeleton } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
 import { EmptyState } from "@/g8/components/empty-state";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
 import { DetailPanel } from "@/g8/components/screen/detail-panel";
 import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
 import { KeyValueList } from "@/g8/components/screen/key-value-list";
@@ -42,7 +52,13 @@ import {
   type InboxTag,
   type InboxThread,
 } from "../lib/inbox-types";
+import { isNotFound } from "../lib/inbox-manage";
+import { BlockedSenders } from "./blocked-senders";
+import { ComposeMessage } from "./compose-message";
+import { InboxSearch } from "./inbox-search";
 import { ReplyComposer } from "./reply-composer";
+import { TagManager } from "./tag-manager";
+import { ThreadActions } from "./thread-actions";
 import { TagAndAssign } from "./tag-and-assign";
 import { ThreadView } from "./thread-view";
 import { useBrand } from "@/g8/hooks/use-brand";
@@ -66,6 +82,10 @@ export interface InboxScreenProps {
   urlState?: boolean;
   /** Skip the screen header (title, description, stats) when the host page already has one. Default false. */
   hideHeader?: boolean;
+  /** Show the New message, Search all and Manage buttons. Default true. */
+  showManagement?: boolean;
+  /** Show "Manage conversation" (mark read, remove tag, unassign, block sender) under the composer. Default false, so existing embedders see no new controls. */
+  showThreadActions?: boolean;
 }
 
 /** `useUrlState` or plain state, chosen once per mount (the flag must not change while mounted). */
@@ -160,6 +180,7 @@ function ListEmpty({ filtered, onClear }: { filtered: boolean; onClear: () => vo
 
 function ThreadDetails({ thread }: { thread: Selected }) {
   const { data: t, loading, error, refetch } = useInboxThread(thread.id, thread.channel);
+  if (isNotFound(error)) return <EmptyState compact title="Conversation not found" description="It may have been removed, or it is not shared with this API key." />;
   if (error) return <ApiError error={error} title="Could not load this conversation" onRetry={() => void refetch()} />;
   if (!t) return loading ? <Skeleton className="h-24 w-full" /> : null;
   const dash = "";
@@ -185,15 +206,18 @@ function ThreadDetails({ thread }: { thread: Selected }) {
 
 function ExtraTab({ thread, render }: { thread: Selected; render: (thread: InboxThread) => ReactNode }) {
   const { data, loading, error, refetch } = useInboxThread(thread.id, thread.channel);
+  if (isNotFound(error)) return <EmptyState compact title="Conversation not found" description="It may have been removed, or it is not shared with this API key." />;
   if (error) return <ApiError error={error} title="Could not load this conversation" onRetry={() => void refetch()} />;
   if (!data) return loading ? <Skeleton className="h-24 w-full" /> : null;
   return <>{render(data)}</>;
 }
 
-export function InboxScreen({ initialFilters, availableTags, className, toolbarActions, renderRowActions, renderDetailActions, extraDetailTabs, pageSize = 25, urlState = true, hideHeader = false }: InboxScreenProps) {
+export function InboxScreen({ initialFilters, availableTags, className, toolbarActions, renderRowActions, renderDetailActions, extraDetailTabs, pageSize = 25, urlState = true, hideHeader = false, showManagement = true, showThreadActions = false }: InboxScreenProps) {
   const [filters, setFilters] = useState<InboxFilters>(initialFilters ?? {});
   const [page, setPage] = useState(1);
   const [search, setSearch] = useState("");
+  const [sheet, setSheet] = useState<"compose" | "search" | "manage" | null>(null);
+  const [managed, setManaged] = useState<InboxTag[]>([]);
   const [openKey, setOpenKey] = useSelectionState("id", urlState);
   const [view, setView] = useSelectionState("view", urlState);
   const { threads, loading, error, hasNext, total, refetch } = useInboxThreads(filters, page, pageSize);
@@ -202,9 +226,9 @@ export function InboxScreen({ initialFilters, availableTags, className, toolbarA
 
   const tags = useMemo(() => {
     const seen = new Map<string, InboxTag>();
-    for (const t of [...(availableTags ?? []), ...threads.flatMap((th) => th.tags)]) if (t.id) seen.set(t.id, t);
+    for (const t of [...(availableTags ?? []), ...managed, ...threads.flatMap((th) => th.tags)]) if (t.id) seen.set(t.id, t);
     return [...seen.values()];
-  }, [availableTags, threads]);
+  }, [availableTags, managed, threads]);
   const needle = search.trim().toLowerCase();
   const rows = useMemo(
     () => (needle ? threads.filter((t) => `${contactLabel(t)} ${t.contact?.email ?? ""} ${t.contact?.company ?? ""} ${t.subject ?? ""} ${previewText(t, 300)}`.toLowerCase().includes(needle)) : threads),
@@ -222,6 +246,27 @@ export function InboxScreen({ initialFilters, availableTags, className, toolbarA
   const count = (c: string) => threads.filter((t) => t.channel === c).length;
   const first = open ? threads.find((t) => t.id === open.id && t.channel === open.channel) : undefined;
 
+  const management = showManagement ? (
+    <>
+      <Button size="sm" variant="outline" onClick={() => setSheet("search")}><Search className="mr-1 size-4" />Search all</Button>
+      <Button size="sm" variant="outline" onClick={() => setSheet("manage")}><Tags className="mr-1 size-4" />Manage</Button>
+      <Button size="sm" onClick={() => setSheet("compose")}><PenSquare className="mr-1 size-4" />New message</Button>
+    </>
+  ) : null;
+  const sheets = showManagement ? (
+    <>
+      <FormSheet open={sheet === "compose"} onOpenChange={(o) => !o && setSheet(null)} width="lg" title="New message" description="Write to someone new. Nothing is sent until you confirm.">
+        {sheet === "compose" ? <ComposeMessage onCancel={() => setSheet(null)} onSent={() => { setSheet(null); void refetch(); }} /> : null}
+      </FormSheet>
+      <FormSheet open={sheet === "search"} onOpenChange={(o) => !o && setSheet(null)} width="lg" title="Search all conversations" description="Searches your email and LinkedIn on the server, beyond the page loaded here.">
+        {sheet === "search" ? <InboxSearch onOpen={(hit) => { setOpenKey(`${hit.channel}:${hit.id}`); setView(null); setSheet(null); }} /> : null}
+      </FormSheet>
+      <FormSheet open={sheet === "manage"} onOpenChange={(o) => !o && setSheet(null)} width="lg" title="Manage the inbox" description="Tags and blocked senders.">
+        {sheet === "manage" ? <div className="space-y-6"><TagManager onTags={setManaged} /><BlockedSenders /></div> : null}
+      </FormSheet>
+    </>
+  ) : null;
+
   const panes = (
     <>
       <div className={expanded ? "grid gap-4" : "grid gap-4 lg:grid-cols-[minmax(0,2fr)_minmax(0,3fr)]"}>
@@ -268,6 +313,7 @@ export function InboxScreen({ initialFilters, availableTags, className, toolbarA
                           {renderDetailActions ? <div className="flex flex-wrap gap-2">{renderDetailActions(thread)}</div> : null}
                           <ReplyComposer thread={thread} onSent={reload} />
                           <TagAndAssign thread={thread} availableTags={tags} onChanged={reload} />
+                          {showThreadActions ? <ThreadActions thread={thread} onChanged={reload} /> : null}
                         </div>
                       )}
                     </ThreadView>
@@ -289,9 +335,10 @@ export function InboxScreen({ initialFilters, availableTags, className, toolbarA
       <div className={className ? `space-y-4 ${className}` : "space-y-4"}>
         <div className="flex flex-wrap items-center justify-between gap-2">
           <Toolbar search={{ value: search, onChange: setSearch, placeholder: "Search this page" }} filters={<Filters filters={filters} tags={tags} update={update} />} />
-          <div className="flex gap-2"><Button size="sm" variant="outline" onClick={() => void refetch()}><RefreshCw className="mr-1 size-4" />Refresh</Button>{toolbarActions}</div>
+          <div className="flex gap-2"><Button size="sm" variant="outline" onClick={() => void refetch()}><RefreshCw className="mr-1 size-4" />Refresh</Button>{management}{toolbarActions}</div>
         </div>
         {panes}
+        {sheets}
       </div>
     );
   }
@@ -301,7 +348,7 @@ export function InboxScreen({ initialFilters, availableTags, className, toolbarA
       title="Inbox"
       description="Every reply across email, SMS and LinkedIn in one queue."
       icon={<InboxIcon className="size-5" />}
-      actions={<><Button size="sm" variant="outline" onClick={() => void refetch()}><RefreshCw className="mr-1 size-4" />Refresh</Button>{toolbarActions}</>}
+      actions={<><Button size="sm" variant="outline" onClick={() => void refetch()}><RefreshCw className="mr-1 size-4" />Refresh</Button>{management}{toolbarActions}</>}
       stats={[
         { label: "Conversations", value: total != null ? total.toLocaleString() : threads.length, hint: total != null ? "in this view" : "on this page" },
         { label: "Drafts waiting", value: drafts, hint: "on this page", tone: drafts > 0 ? "warning" : "neutral" },
@@ -311,6 +358,7 @@ export function InboxScreen({ initialFilters, availableTags, className, toolbarA
       toolbar={<Toolbar search={{ value: search, onChange: setSearch, placeholder: "Search this page" }} filters={<Filters filters={filters} tags={tags} update={update} />} />}
     >
       {panes}
+      {sheets}
     </ScreenLayout>
   );
 }

package/blocks/inbox/components/inbox-search.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+/**
+ * InboxSearch: search ALL of your email threads or LinkedIn conversations on the server, not just the page the list
+ * has loaded. Type, press Enter (or Search), pick a result; `onOpen` receives the thread's channel and id so a screen
+ * can open it in its conversation view.
+ *
+ * SDK operations, in order:
+ *   Email:    1. GET  /inbox/mailboxes/paginated                    (aiInbox.listInboxMailboxesPaginated)  READ - the mailboxes searched
+ *             2. POST /inbox/emails/search?page&page_size            (inbox.searchInboxEmails)              READ - `mailboxes` is required
+ *                (an empty mailbox list is "no result", never "all", so every mailbox you can see is sent)
+ *   LinkedIn: POST /inbox/linkedin/conversations/search             (aiInbox.searchInboxLinkedinConversations)  READ
+ * SMS threads have no search route in the API; they are found in the list. Searching sends nothing and costs nothing.
+ * Result rows are untyped in the contract, so they are read defensively; opening one loads the real thread
+ * (ThreadView), and a thread the key may not see answers a uniform 404 which the thread view explains.
+ */
+import { useState } from "react";
+import { Search } from "lucide-react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { FirstNotice } from "@/g8/components/paging-notices";
+import { useInboxMailboxes } from "../hooks/use-inbox-mailboxes";
+import { formatWhen } from "../lib/inbox-types";
+import { rowsFrom, searchHit } from "../lib/inbox-manage";
+import type { SearchHit } from "../lib/inbox-manage";
+
+export interface InboxSearchProps {
+  /** Called with the chosen result's channel and thread id. */
+  onOpen?: (hit: { channel: "email" | "linkedin"; id: string }) => void;
+  pageSize?: number;
+  className?: string;
+}
+
+type Channel = "email" | "linkedin";
+
+export function InboxSearch({ onOpen, pageSize = 20, className }: InboxSearchProps) {
+  const [channel, setChannel] = useState<Channel>("email");
+  const [text, setText] = useState("");
+  const [submitted, setSubmitted] = useState<{ channel: Channel; q: string; page: number } | null>(null);
+  const mailboxes = useInboxMailboxes({ enabled: channel === "email" });
+  const results = useG8Query(
+    async (signal): Promise<{ hits: SearchHit[]; hasNext: boolean }> => {
+      const s = submitted!;
+      if (s.channel === "email") {
+        const env = await g8Post("/inbox/emails/search", { mailboxes: (mailboxes.data ?? []).map((m) => m.address), search: s.q, sort_by: "updated_at", sort_order: "desc" }, { query: { page: s.page, page_size: pageSize }, signal });
+        const hits = rowsFrom<Record<string, unknown>>(env, "emails").map((r) => searchHit("email", r)).filter((h): h is SearchHit => h != null);
+        return { hits, hasNext: Boolean((env.pagination as { has_next?: boolean } | undefined)?.has_next) || hits.length >= pageSize };
+      }
+      const env = await g8Post("/inbox/linkedin/conversations/search", { search: s.q, limit: pageSize, offset: (s.page - 1) * pageSize, sort_order: "desc" }, { signal });
+      const hits = rowsFrom<Record<string, unknown>>(env, "conversations").map((r) => searchHit("linkedin", r)).filter((h): h is SearchHit => h != null);
+      return { hits, hasNext: hits.length >= pageSize };
+    },
+    [submitted?.channel, submitted?.q, submitted?.page, submitted ? (mailboxes.data ?? []).length : 0],
+    { enabled: submitted != null && (submitted.channel !== "email" || mailboxes.data != null) },
+  );
+
+  const run = () => {
+    const q = text.trim();
+    if (q) setSubmitted({ channel, q, page: 1 });
+  };
+  const hits = results.data?.hits ?? [];
+
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <form className="flex flex-wrap items-center gap-2" role="search" onSubmit={(e) => { e.preventDefault(); run(); }}>
+        <div role="group" aria-label="Search in" className="flex gap-1">
+          <Button type="button" size="sm" variant={channel === "email" ? "default" : "outline"} onClick={() => { setChannel("email"); setSubmitted(null); }}>Email</Button>
+          <Button type="button" size="sm" variant={channel === "linkedin" ? "default" : "outline"} onClick={() => { setChannel("linkedin"); setSubmitted(null); }}>LinkedIn</Button>
+        </div>
+        <Input aria-label="Search all conversations" className="min-w-48 flex-1" placeholder={channel === "email" ? "Subject, sender or text" : "Name or message text"} value={text} onChange={(e) => setText(e.target.value)} />
+        <Button type="submit" size="sm" disabled={!text.trim()}><Search className="mr-1 size-4" aria-hidden />Search</Button>
+      </form>
+      {channel === "email" ? <FirstNotice shown={mailboxes.items.length} limit={0} force={mailboxes.truncated} noun="mailboxes" /> : null}
+      {mailboxes.error && channel === "email" ? <ApiError error={mailboxes.error} title="Could not load your mailboxes" onRetry={() => void mailboxes.refetch()} /> : null}
+      {channel === "email" && mailboxes.data && mailboxes.data.length === 0 ? <p className="text-sm text-muted-foreground">No mailbox is connected yet, so there is nothing to search.</p> : null}
+      {results.error ? <ApiError error={results.error} title="The search failed" onRetry={() => void results.refetch()} /> : null}
+      {submitted && results.loading && !results.data ? <div aria-busy="true" className="space-y-2"><Skeleton className="h-14 w-full" /><Skeleton className="h-14 w-full" /></div> : null}
+      {submitted && results.data && hits.length === 0 ? <EmptyState compact title="No conversations found" description={`Nothing matches "${submitted.q}".`} /> : null}
+      {hits.length > 0 ? (
+        <ul aria-label="Search results" className="divide-y rounded-md border border-border">
+          {hits.map((h) => (
+            <li key={`${h.channel}:${h.id}`}>
+              <button type="button" className="flex w-full flex-col gap-0.5 p-3 text-left hover:bg-muted/50" onClick={() => onOpen?.({ channel: h.channel, id: h.id })}>
+                <span className="flex items-center justify-between gap-2"><span className="truncate text-sm font-medium">{h.title}</span><span className="shrink-0 text-xs text-muted-foreground">{formatWhen(h.when)}</span></span>
+                {h.subtitle ? <span className="truncate text-xs text-muted-foreground">{h.subtitle}</span> : null}
+                {h.preview ? <span className="truncate text-xs">{h.preview}</span> : null}
+              </button>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      {submitted && results.data && (submitted.page > 1 || results.data.hasNext) ? (
+        <div className="flex items-center justify-between text-sm text-muted-foreground">
+          <span>Page {submitted.page}</span>
+          <div className="flex gap-2">
+            <Button size="sm" variant="outline" disabled={submitted.page <= 1 || results.loading} onClick={() => setSubmitted({ ...submitted, page: submitted.page - 1 })}>Previous</Button>
+            <Button size="sm" variant="outline" disabled={!results.data.hasNext || results.loading} onClick={() => setSubmitted({ ...submitted, page: submitted.page + 1 })}>Next</Button>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/blocks/inbox/components/record-conversations-tab.tsx

@@ -0,0 +1,154 @@
+"use client";
+
+/**
+ * RecordConversationsTab: the email conversations with one contact, newest first, "Load more" for older ones. Opening a row
+ * shows its messages. Use it as an `extraDetailTabs` entry of ContactsScreen:
+ *   { id: "conversations", label: "Conversations", render: (c) => <RecordConversationsTab email={c.work_email} onOpenThread={(sel) => router.push(`/inbox?id=${sel}`)} /> }
+ *
+ * SDK operations, in order:
+ *   1. listInboxMailboxes  GET  /inbox/mailboxes                          (read; the mailboxes this key can read: search requires them)
+ *   2. searchInboxEmails   POST /inbox/emails/search?page=&page_size=     (read; body `{ mailboxes, search_emails: [email] }`, 10 per page)
+ *   3. getReply            GET  /inbox/{id}?channel=email                 (read; only when a row is opened)
+ * The inbox has no filter by contact id, so the contact is matched by email address (sender or recipient): `email` plus any
+ * `alsoEmails`. A contact with no usable address has no conversations to show. SMS and LinkedIn threads are not matched here.
+ *
+ * Hidden threads: the API answers a thread the key may not see exactly like one that does not exist (404, the same text).
+ * A row that 404s on open says "not available to you" instead of an error with a retry button.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { MessagesSquare } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { usePaginated } from "@/g8/hooks/use-paginated";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useInboxThread } from "../hooks/use-inbox-thread";
+import { formatWhen, stripHtml, type InboxMessage } from "../lib/inbox-types";
+
+const PAGE_SIZE = 10;
+
+/** One thread of POST /inbox/emails/search. Only the fields shown here are read; all are optional. */
+interface FoundThread { id?: string | number | null; email_id?: string | number | null; subject?: string | null; updated_at?: string | null; created_at?: string | null; status?: string | null; messages?: InboxMessage[] | null }
+
+const idOf = (t: FoundThread): string => String(t.id ?? t.email_id ?? "");
+const statusOf = (e: unknown): number | undefined => (e as { status?: number } | null)?.status;
+
+/** Mailbox addresses from GET /inbox/mailboxes (rows are mailbox records; the address is `email`). */
+function mailboxAddresses(env: unknown): string[] {
+  const data = (env as { data?: unknown } | null)?.data;
+  const rows = Array.isArray(data) ? data : ((data as { items?: unknown } | null)?.items ?? []);
+  const out = new Set<string>();
+  for (const r of Array.isArray(rows) ? rows : []) {
+    const row = r as { email?: string | null; mailbox?: string | null };
+    const address = (row.email ?? row.mailbox ?? "").trim();
+    if (address) out.add(address);
+  }
+  return [...out];
+}
+
+function Opened({ id }: { id: string }) {
+  const t = useInboxThread(id, "email");
+  if (t.error) {
+    return statusOf(t.error) === 404
+      ? <p role="status" className="p-3 text-sm text-muted-foreground">This conversation is not available to you. It may have been removed, or it belongs to a mailbox you cannot read.</p>
+      : <div className="p-3"><ApiError error={t.error} title="Could not load this conversation" onRetry={() => void t.refetch()} /></div>;
+  }
+  if (!t.data) return <Skeleton className="m-3 h-16 w-auto" aria-label="Loading conversation" />;
+  const messages = t.data.messages.filter((m) => !m.is_draft);
+  if (messages.length === 0) return <p className="p-3 text-sm text-muted-foreground">No messages in this conversation yet.</p>;
+  return (
+    <ol className="space-y-2 p-3" aria-label="Messages">
+      {messages.map((m, i) => (
+        <li key={m.message_id ?? i} className="rounded-md border p-3 text-sm">
+          <p className="mb-1 flex flex-wrap gap-2 text-xs text-muted-foreground"><span className="font-medium text-foreground">{m.from_address ?? "Unknown sender"}</span>{m.date ? <span>{formatWhen(m.date)}</span> : null}</p>
+          <p className="whitespace-pre-wrap">{stripHtml(m.content) || "(no content)"}</p>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+export interface RecordConversationsTabProps {
+  /** The contact's email address. Without one the tab explains there is nothing to match. */
+  email: string | null | undefined;
+  /** Other addresses of the contact (personal or additional emails; a comma-separated string is fine). Threads with any of them are shown. */
+  alsoEmails?: ReadonlyArray<string | null | undefined>;
+  /** Route to the conversation in your inbox screen; receives the inbox selection ("email:<id>"). Without it the rows link to `${inboxPath}?id=email:<id>`. */
+  onOpenThread?: (selection: string) => void;
+  /** Path of your inbox screen for the plain links. Default "/inbox". */
+  inboxPath?: string;
+}
+
+export function RecordConversationsTab({ email, alsoEmails = [], onOpenThread, inboxPath = "/inbox" }: RecordConversationsTabProps) {
+  const addresses = [...new Set([email, ...alsoEmails].flatMap((e) => (e ?? "").split(",")).map((e) => e.trim()).filter((e) => e !== "" && !e.includes("*") && e.includes("@")))];
+  const usable = addresses.length > 0;
+  const boxes = useG8Query(async (signal) => mailboxAddresses(await g8Get("/inbox/mailboxes", undefined, { signal })), [usable], { enabled: usable });
+  const mailboxes = boxes.data ?? [];
+
+  if (!usable) return <EmptyState compact icon={<MessagesSquare className="size-8" />} title="No email address" description="Conversations are matched by email address, and this contact has none to match." />;
+  if (boxes.error) return <ApiError error={boxes.error} title="Could not load mailboxes" onRetry={() => void boxes.refetch()} />;
+  if (!boxes.data) return <Skeleton className="h-24 w-full" aria-label="Loading conversations" />;
+  if (mailboxes.length === 0) return <EmptyState compact icon={<MessagesSquare className="size-8" />} title="No mailbox connected" description="Connect a mailbox to see the conversations you have with this contact." />;
+  // Mounted only once the mailboxes are known, so its first render is already "loading" (no empty-state flash before the first search).
+  return <ConversationList addresses={addresses} mailboxes={mailboxes} onOpenThread={onOpenThread} inboxPath={inboxPath} />;
+}
+
+interface ConversationListProps { addresses: string[]; mailboxes: string[]; onOpenThread?: (selection: string) => void; inboxPath: string }
+
+function ConversationList({ addresses, mailboxes, onOpenThread, inboxPath }: ConversationListProps) {
+  const [open, setOpen] = useState<string | null>(null);
+  const list = usePaginated<FoundThread>(async (cursor, signal) => {
+    const page = cursor ? Number(cursor) || 1 : 1;
+    const env = await g8Post<{ items?: FoundThread[] }>(`/inbox/emails/search?page=${page}&page_size=${PAGE_SIZE}`, { mailboxes, search_emails: addresses }, { signal });
+    const items = (env.data?.items ?? []).filter((t) => idOf(t) !== "");
+    const more = (env as { pagination?: { has_next?: boolean } }).pagination?.has_next ?? items.length >= PAGE_SIZE;
+    return { data: items, pagination: { next_cursor: more && items.length > 0 ? String(page + 1) : null } } as never;
+  }, [addresses.join(","), mailboxes.join("|")]);
+
+  if (list.error) return <ApiError error={list.error} title="Could not load conversations" onRetry={() => void list.reload()} />;
+  if (list.loading && list.items.length === 0) return <Skeleton className="h-24 w-full" aria-label="Loading conversations" />;
+  if (list.items.length === 0) return <EmptyState compact icon={<MessagesSquare className="size-8" />} title="No conversations yet" description="Emails sent to or received from this contact show up here." />;
+
+  return (
+    <div className="space-y-2">
+      <ul className="divide-y rounded-md border" aria-label="Conversations">
+        {list.items.map((t) => {
+          const id = idOf(t);
+          const last = (t.messages ?? []).filter((m) => !m.is_draft).slice(-1)[0];
+          const isOpen = open === id;
+          const selection = `email:${id}`;
+          return (
+            <li key={id}>
+              <div className="flex items-center justify-between gap-3 p-3 text-sm">
+                <button type="button" aria-expanded={isOpen} className="min-w-0 flex-1 text-left" onClick={() => setOpen(isOpen ? null : id)}>
+                  <span className="block truncate font-medium">{t.subject || "(no subject)"}</span>
+                  <span className="block truncate text-xs text-muted-foreground">{[formatWhen(t.updated_at ?? t.created_at), last ? stripHtml(last.content).slice(0, 80) : null].filter(Boolean).join(" · ")}</span>
+                </button>
+                <a
+                  href={`${inboxPath}?id=${encodeURIComponent(selection)}`}
+                  className="shrink-0 text-xs text-muted-foreground hover:underline"
+                  onClick={(e) => {
+                    if (!onOpenThread || e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+                    e.preventDefault();
+                    onOpenThread(selection);
+                  }}
+                >
+                  Open in inbox
+                </a>
+              </div>
+              {isOpen ? <Opened id={id} /> : null}
+            </li>
+          );
+        })}
+      </ul>
+      {list.hasMore ? (
+        <div className="flex items-center justify-between text-sm text-muted-foreground">
+          <span role="status">Showing {list.items.length.toLocaleString()} conversations</span>
+          <Button size="sm" variant="outline" loading={list.loadingMore} onClick={() => void list.loadMore()}>Load more</Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/blocks/inbox/components/tag-manager.tsx

@@ -0,0 +1,136 @@
+"use client";
+
+/**
+ * TagManager: the inbox tag library. See every tag, create one, rename or recolour one, delete one.
+ *
+ * SDK operations, in order:
+ *   1. GET    /workflows/inbox-tags       (workflows.listInboxTags)  READ         - every tag, with its built-in policy
+ *   2. POST   /inbox/tags                 (aiInbox.createInboxTag)   write
+ *   3. PUT    /inbox/tags/{tag_id}        (aiInbox.updateInboxTag)   write        - ONLY the fields that changed
+ *   4. DELETE /inbox/tags/{tag_id}        (aiInbox.deleteInboxTag)   DESTRUCTIVE  -> ConfirmSpendDialog first
+ *
+ * Built-in tags follow the API's policy: "system" tags cannot be edited or deleted, "sdr_ai" tags cannot be renamed
+ * or deleted. Deleting a tag removes the label from every conversation that carries it (nothing else is removed).
+ * The edit form is seeded from a LOADED row and its Save stays disabled until something changed; it never writes a
+ * tag that was not loaded, and the request carries only the changed fields (a partial PUT must not reset
+ * `ai_can_apply` or the rules, which this form does not show). Applying a tag to a conversation is TagAndAssign.
+ */
+import { useEffect, useState } from "react";
+import { Pencil, Plus, Trash2 } from "lucide-react";
+import { Button, Input, Skeleton } 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 { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import type { InboxTag } from "../lib/inbox-types";
+import { asInboxTags, canDeleteTag, canEditTag, canRenameTag, isHexColor, managedTags, tagChanges } from "../lib/inbox-manage";
+import type { ManagedTag } from "../lib/inbox-manage";
+
+export interface TagManagerProps {
+  /** Called with the current tag list after every load and change, so a screen can keep its pickers in step. */
+  onTags?: (tags: InboxTag[]) => void;
+  className?: string;
+}
+
+function TagForm({ tag, onDone }: { tag: ManagedTag | null; onDone: (changed: boolean) => void }) {
+  const [name, setName] = useState(tag?.name ?? "");
+  const [description, setDescription] = useState(tag?.description ?? "");
+  const [color, setColor] = useState(tag?.color ?? "");
+  useEffect(() => {
+    setName(tag?.name ?? "");
+    setDescription(tag?.description ?? "");
+    setColor(tag?.color ?? "");
+  }, [tag?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+  const changes = tag ? tagChanges(tag, { name, description, color }) : {};
+  const save = useG8Mutation(async () => {
+    if (tag) await g8Put(`/inbox/tags/${encodeURIComponent(tag.id)}`, changes);
+    else await g8Post("/inbox/tags", { name: name.trim(), ...(description.trim() ? { description: description.trim() } : {}), ...(color.trim() ? { color: color.trim() } : {}) });
+  }, { invalidates: ["inbox"] });
+  const valid = name.trim().length > 0 && isHexColor(color) && (tag ? Object.keys(changes).length > 0 : true);
+  const submit = async () => {
+    try {
+      await save.mutateAsync(undefined);
+      onDone(true);
+    } catch {
+      /* the error renders in the form; the typed values stay */
+    }
+  };
+  return (
+    <form className="space-y-2 rounded-md border border-border p-3" onSubmit={(e) => { e.preventDefault(); if (valid) void submit(); }} aria-label={tag ? `Edit ${tag.name}` : "New tag"}>
+      <Input aria-label="Tag name" placeholder="Tag name" value={name} disabled={tag ? !canRenameTag(tag) : false} onChange={(e) => setName(e.target.value)} />
+      <Input aria-label="Description" placeholder="What this tag means (optional)" value={description} onChange={(e) => setDescription(e.target.value)} />
+      <div className="flex items-center gap-2">
+        <Input aria-label="Colour" className="w-32" placeholder="#eab308" value={color} onChange={(e) => setColor(e.target.value)} />
+        {!isHexColor(color) ? <span role="alert" className="text-xs text-error-foreground">Use a hex colour such as #eab308.</span> : null}
+      </div>
+      {save.error ? <ApiError error={save.error} title={tag ? "Could not save the tag" : "Could not create the tag"} /> : null}
+      <div className="flex justify-end gap-2">
+        <Button type="button" variant="outline" size="sm" onClick={() => onDone(false)}>Cancel</Button>
+        <Button type="submit" size="sm" disabled={!valid || save.loading}>{tag ? "Save changes" : "Create tag"}</Button>
+      </div>
+    </form>
+  );
+}
+
+export function TagManager({ onTags, className }: TagManagerProps) {
+  const [editing, setEditing] = useState<ManagedTag | "new" | null>(null);
+  const [deleting, setDeleting] = useState<ManagedTag | null>(null);
+  const tags = useG8Query(async (signal) => managedTags(await g8Get("/workflows/inbox-tags", undefined, { signal })), [], { key: ["inbox", "tags"] });
+  useEffect(() => { if (tags.data) onTags?.(asInboxTags(tags.data)); }, [tags.data]); // eslint-disable-line react-hooks/exhaustive-deps
+  const remove = useG8Mutation(async (tag: ManagedTag) => {
+    await g8Delete(`/inbox/tags/${encodeURIComponent(tag.id)}`);
+    setDeleting(null);
+    await tags.refetch();
+  }, { invalidates: ["inbox"], onError: () => setDeleting(null) });
+
+  if (tags.error) return <ApiError error={tags.error} title="Could not load the tags" onRetry={() => void tags.refetch()} className={className} />;
+  if (tags.loading && !tags.data) return <div aria-busy="true" className={`space-y-2 ${className ?? ""}`}><Skeleton className="h-10 w-full" /><Skeleton className="h-10 w-full" /></div>;
+  const rows = tags.data ?? [];
+  const done = (changed: boolean) => { setEditing(null); if (changed) void tags.refetch(); };
+
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <div className="flex items-center justify-between">
+        <h3 className="font-medium">Tags</h3>
+        <Button size="sm" variant="outline" disabled={editing != null} onClick={() => setEditing("new")}><Plus className="mr-1 size-4" aria-hidden />New tag</Button>
+      </div>
+      {editing === "new" ? <TagForm tag={null} onDone={done} /> : null}
+      {rows.length === 0 && editing !== "new" ? (
+        <EmptyState compact title="No tags yet" description="Tags label conversations so you can filter and route them." action={<Button size="sm" onClick={() => setEditing("new")}>Create a tag</Button>} />
+      ) : (
+        <ul aria-label="Tags" className="divide-y rounded-md border border-border">
+          {rows.map((t) => (
+            <li key={t.id} className="p-2 text-sm">
+              {editing !== "new" && editing?.id === t.id ? (
+                <TagForm tag={t} onDone={done} />
+              ) : (
+                <div className="flex items-center gap-2">
+                  <span aria-hidden className="size-3 shrink-0 rounded-full border border-border" style={t.color ? { backgroundColor: t.color } : undefined} />
+                  <span className="min-w-0 flex-1"><span className="font-medium">{t.name}</span>{t.description ? <span className="block truncate text-xs text-muted-foreground">{t.description}</span> : null}</span>
+                  {t.policy !== "user" ? <StatusPill tone="neutral">built in</StatusPill> : null}
+                  <Button size="sm" variant="ghost" aria-label={`Edit ${t.name}`} disabled={!canEditTag(t) || editing != null} onClick={() => setEditing(t)}><Pencil className="size-4" aria-hidden /></Button>
+                  <Button size="sm" variant="ghost" aria-label={`Delete ${t.name}`} disabled={!canDeleteTag(t)} onClick={() => setDeleting(t)}><Trash2 className="size-4" aria-hidden /></Button>
+                </div>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the tag" /> : null}
+      <ConfirmSpendDialog
+        open={deleting != null}
+        tier="destructive"
+        title={`Delete the tag "${deleting?.name ?? ""}"?`}
+        description="Every conversation loses this label. The conversations themselves are not touched. This cannot be undone."
+        confirmLabel="Delete tag"
+        affected={1}
+        confirming={remove.loading}
+        onConfirm={() => deleting && void remove.mutate(deleting)}
+        onCancel={() => setDeleting(null)}
+      />
+    </div>
+  );
+}