@graph8/sdk 0.361.0 → 0.370.0

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

@@ -0,0 +1,222 @@
+"use client";
+
+/**
+ * CoachScreen: the finished sales coach page. Tabs: Practice calls (graded calls newest first with a score and the first
+ * tip; open one for the full scorecard, recording and transcript, deep link `?id=`), Leaderboard (reps ranked by score) and
+ * Real calls (the rep's dialer calls, only when a rep email is known). Stats summarise the loaded calls: how many, the
+ * average and best score, and the stage reps miss most.
+ *
+ * Flows: browse and open calls; load a signed recording (CallScorecard); delete a call (destructive, ConfirmSpendDialog;
+ * hide with allowDelete={false}); create a practice call row (write; the live practice conversation itself runs in the
+ * graph8 app, so the form links out); managers type a rep's email to read that rep's calls (needs a manager key, a 403 is shown).
+ *
+ * SDK operations (through the composed parts): GET /sales-coach/calls, GET /sales-coach/leaderboard, POST /sales-coach/calls,
+ * and CallScorecard's getCall, getCallTranscript, getCallAudioUrl and deleteCall; GET /voice/dialer/calls via the dialer block.
+ */
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { GraduationCap } from "lucide-react";
+import { Button, Input, Label, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+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 { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { CallHistory } from "@/g8/dialer/components/call-log-screen";
+import { avgOf, listOf, scorecardOf } from "../lib/coach-types";
+import type { CoachCall, LeaderboardRow } from "../lib/coach-types";
+import { CallScorecard } from "./call-scorecard";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface CoachScreenProps {
+  /** Whose practice calls. Omit for the key owner's own; managers may type another rep's email. */
+  userEmail?: string;
+  /** Show the "New practice call" button (creates the row only). Default true when no rep email is set. */
+  allowCreate?: boolean;
+  allowDelete?: boolean;
+  toolbarActions?: ReactNode;
+  renderRowActions?: (call: CoachCall) => ReactNode;
+  renderDetailActions?: (call: CoachCall) => ReactNode;
+  extraDetailTabs?: Array<{ id: string; label: string; render: (call: CoachCall) => ReactNode }>;
+  className?: string;
+}
+
+function useDebounced<T>(value: T, ms = 400): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}
+
+const scoreTone = (pct: number | null | undefined) => (pct == null ? "neutral" : pct >= 75 ? "positive" : pct >= 50 ? "warning" : "negative");
+const EMPTY_FORM = { call_mode: "assisted" as "assisted" | "compete", prospect_name: "", prospect_company: "", persona_type: "" };
+
+function weakestStage(rows: CoachCall[]): string | null {
+  const sums = new Map<string, { total: number; n: number }>();
+  for (const c of rows) for (const s of scorecardOf(c)?.stages ?? []) if (s.pct != null) sums.set(s.label, { total: (sums.get(s.label)?.total ?? 0) + s.pct, n: (sums.get(s.label)?.n ?? 0) + 1 });
+  const ranked = [...sums].map(([k, v]) => [k, v.total / v.n] as const).sort((a, b) => a[1] - b[1]);
+  return ranked[0]?.[0] ?? null;
+}
+
+function NewCallSheet({ open, onOpenChange, onCreated }: { open: boolean; onOpenChange: (o: boolean) => void; onCreated: () => void }) {
+  const brand = useBrand();
+  const [form, setForm] = useState(EMPTY_FORM);
+  const create = useG8Mutation(
+    () => g8Post("/sales-coach/calls", { call_mode: form.call_mode, prospect_name: form.prospect_name.trim() || undefined, prospect_company: form.prospect_company.trim() || undefined, persona_type: form.persona_type.trim() || undefined }),
+    { onSuccess: () => { setForm(EMPTY_FORM); onOpenChange(false); onCreated(); } },
+  );
+  const field = (id: string, text: string, key: "prospect_name" | "prospect_company" | "persona_type") => (
+    <div className="flex flex-col gap-1"><Label htmlFor={id}>{text}</Label><Input id={id} value={form[key]} onChange={(e) => setForm({ ...form, [key]: e.target.value })} /></div>
+  );
+  return (
+    <FormSheet
+      open={open}
+      onOpenChange={onOpenChange}
+      title="New practice call"
+      description={`This adds the call to your list. The live practice conversation runs in ${brand.linkLabel}.`}
+      footer={<><Button variant="ghost" onClick={() => onOpenChange(false)}>Cancel</Button><Button loading={create.loading} onClick={() => void create.mutate(undefined)}>Create call</Button></>}
+    >
+      <div className="grid gap-3">
+        {field("pc-name", "Prospect", "prospect_name")}
+        {field("pc-company", "Company", "prospect_company")}
+        {field("pc-persona", "Persona", "persona_type")}
+        <div className="flex flex-col gap-1"><Label htmlFor="pc-mode">Mode</Label>
+          <select id="pc-mode" className="h-9 rounded-md border border-border bg-background px-2 text-sm" value={form.call_mode} onChange={(e) => setForm({ ...form, call_mode: e.target.value as "assisted" | "compete" })}><option value="assisted">Training</option><option value="compete">Compete</option></select>
+        </div>
+        {create.error ? <ApiError error={create.error} title="Could not create the call" /> : null}
+        <a className="text-sm underline" href={brand.appUrl} target="_blank" rel="noreferrer">Practice in {brand.linkLabel}</a>
+      </div>
+    </FormSheet>
+  );
+}
+
+function Leaderboard({ enabled }: { enabled: boolean }) {
+  const board = useG8Query((signal) => g8Get("/sales-coach/leaderboard", undefined, { signal }), [], { enabled });
+  const ranked = [...listOf<LeaderboardRow>(board.data, "items")].sort((a, b) => b.score - a.score);
+  if (board.error) return <ApiError error={board.error} title="Could not load the leaderboard" onRetry={() => void board.refetch()} />;
+  if (board.loading && ranked.length === 0) return <Skeleton className="h-32 w-full" aria-label="Loading leaderboard" />;
+  if (ranked.length === 0) return <EmptyState title="Nobody on the board yet" description="Completed practice calls rank here." />;
+  return (
+    <Table>
+      <TableHeader><TableRow><TableHead className="w-12">#</TableHead><TableHead>Rep</TableHead><TableHead className="text-right">Calls</TableHead><TableHead className="text-right">Avg</TableHead><TableHead className="text-right">Total</TableHead></TableRow></TableHeader>
+      <TableBody>
+        {ranked.map((r, i) => (
+          <TableRow key={r.email} data-testid={`rank-${r.email}`}>
+            <TableCell>{i + 1}</TableCell>
+            <TableCell><span className="flex items-center gap-2"><EntityAvatar name={r.name || r.email} kind="person" size="sm" />{r.name}<span className="text-xs text-muted-foreground">{r.email}</span></span></TableCell>
+            <TableCell className="text-right">{r.calls}</TableCell><TableCell className="text-right">{avgOf(r)}</TableCell><TableCell className="text-right">{r.score}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+
+export function CoachScreen(props: CoachScreenProps) {
+  const brand = useBrand();
+  const { allowDelete, toolbarActions, renderRowActions, renderDetailActions, extraDetailTabs, className } = props;
+  const [tab, setTab] = useUrlState("tab", "calls");
+  const [openId, setOpenId] = useUrlState("id");
+  const [view, setView] = useUrlState("view");
+  const [typed, setTyped] = useState("");
+  const [shown, setShown] = useState(15);
+  const [creating, setCreating] = useState(false);
+  const typedEmail = useDebounced(typed.trim());
+  const email = props.userEmail || typedEmail || undefined;
+  const allowCreate = props.allowCreate ?? !email;
+
+  const calls = useG8Query((signal) => g8Get("/sales-coach/calls", { email }, { signal }), [email]);
+  // Another rep's calls are a different list: forget the selection and paging.
+  const lastEmail = useRef(email);
+  useEffect(() => {
+    if (lastEmail.current === email) return; // keep a deep-linked ?id= on first render
+    lastEmail.current = email;
+    setShown(15);
+    setOpenId(null);
+  }, [email]); // eslint-disable-line react-hooks/exhaustive-deps
+  const rows = listOf<CoachCall>(calls.data, "items");
+  const selected = openId ? rows.find((c) => c.id === openId) : undefined;
+  const cards = useMemo(() => rows.map((c) => scorecardOf(c)?.scorePct).filter((n): n is number => typeof n === "number"), [rows]);
+  const avg = cards.length ? Math.round(cards.reduce((a, b) => a + b, 0) / cards.length) : null;
+  const tabs = [{ id: "calls", label: "Practice calls", count: rows.length || undefined }, { id: "board", label: "Leaderboard" }, ...(email ? [{ id: "real", label: "Real calls" }] : [])];
+  const active = tabs.some((t) => t.id === tab) ? tab : "calls";
+
+  const list = (
+    <div className="space-y-2">
+      {calls.error ? <ApiError error={calls.error} title="Could not load practice calls" onRetry={() => void calls.refetch()} /> : null}
+      {calls.loading && rows.length === 0 ? Array.from({ length: 3 }, (_, i) => <Skeleton key={i} className="h-16 w-full" />) : null}
+      <ul className="flex flex-col gap-2" data-testid="feed">
+        {rows.slice(0, shown).map((c) => {
+          const card = scorecardOf(c);
+          const tip = card?.improvements[0];
+          return (
+            <li key={c.id} className="flex items-start gap-1">
+              <button type="button" data-testid={`call-${c.id}`} onClick={() => setOpenId(c.id)} className={`min-w-0 flex-1 rounded-md border border-border p-3 text-left ${openId === c.id ? "bg-muted" : "hover:bg-muted/50"}`}>
+                <span className="flex items-center justify-between gap-2">
+                  <span className="truncate font-medium">{c.prospect_name || "Practice call"}{c.prospect_company ? ` at ${c.prospect_company}` : ""}</span>
+                  {card?.scorePct != null ? <StatusPill tone={scoreTone(card.scorePct)}>{`${Math.round(card.scorePct)}%`}</StatusPill> : <StatusPill tone="neutral">{c.call_status ?? "not graded"}</StatusPill>}
+                </span>
+                <span className="block text-xs text-muted-foreground">{c.date_of_call ? new Date(c.date_of_call).toLocaleDateString() : ""} {c.call_mode ?? ""}</span>
+                {tip ? <span className="mt-1 block text-sm">Work on: {tip}</span> : null}
+              </button>
+              {renderRowActions ? <div className="shrink-0 p-1">{renderRowActions(c)}</div> : null}
+            </li>
+          );
+        })}
+      </ul>
+      {!calls.loading && !calls.error && rows.length === 0 ? (
+        <EmptyState icon={<GraduationCap className="size-6" />} title="No practice calls yet" description={`Graded practice calls and what to work on next show up here. Practice calls run in ${brand.linkLabel}.`} action={allowCreate ? <Button size="sm" onClick={() => setCreating(true)}>New practice call</Button> : undefined} />
+      ) : null}
+      {rows.length > shown ? <Button variant="outline" size="sm" onClick={() => setShown(shown + 15)}>Show more</Button> : null}
+    </div>
+  );
+  const expanded = view === "full" && Boolean(openId);
+  const detail = openId ? (
+    <DetailPanel
+      title={selected?.prospect_name || "Practice call"}
+      subtitle={selected?.prospect_company ?? undefined}
+      actions={selected ? renderDetailActions?.(selected) : undefined}
+      onClose={() => { setOpenId(null); setView(null); }}
+      onExpand={expanded ? undefined : () => setView("full")}
+      onCollapse={expanded ? () => setView(null) : undefined}
+      tabs={[
+        { id: "scorecard", label: "Scorecard", content: <CallScorecard key={openId} callId={openId} allowDelete={allowDelete} onDeleted={() => { setOpenId(null); setView(null); void calls.refetch(); }} /> },
+        ...(selected ? (extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })) : []),
+      ]}
+    />
+  ) : null;
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Sales coach"
+      description="Scored practice calls, what to work on next, and how the team ranks."
+      icon={<GraduationCap className="size-5" />}
+      actions={<>{allowCreate ? <Button size="sm" onClick={() => setCreating(true)}>New practice call</Button> : null}{toolbarActions}</>}
+      tabs={tabs}
+      activeTab={active}
+      onTabChange={(id) => { setTab(id); setOpenId(null); setView(null); }}
+      stats={rows.length > 0 ? [
+        { label: "Calls loaded", value: rows.length },
+        { label: "Average score", value: avg != null ? `${avg}%` : "", tone: scoreTone(avg) },
+        { label: "Best score", value: cards.length ? `${Math.round(Math.max(...cards))}%` : "" },
+        { label: "Weakest stage", value: weakestStage(rows) ?? "", hint: "lowest average" },
+      ] : undefined}
+      toolbar={props.userEmail ? undefined : <Toolbar search={{ value: typed, onChange: setTyped, placeholder: "Rep email (managers)" }} />}
+    >
+      {active === "calls" ? <SplitView list={list} detail={detail} detailOpen={Boolean(openId)} onCloseDetail={() => { setOpenId(null); setView(null); }} expanded={expanded} onExpandedChange={(next) => setView(next ? "full" : null)} /> : null}
+      {active === "board" ? <Leaderboard enabled /> : null}
+      {active === "real" ? <CallHistory userEmail={email} idParam="call" /> : null}
+      <NewCallSheet open={creating} onOpenChange={setCreating} onCreated={() => void calls.refetch()} />
+    </ScreenLayout>
+  );
+}

package/blocks/copilot/README.md

@@ -4,6 +4,19 @@ Drop an "Ask graph8" side panel into your app. It chats with the copilot (which
 copy and propose changes), chats in a Work channel where agents answer, and manages what the copilot
 remembers. Everything is request/response or polled: the API has no streams.
 
+## Screens
+
+`CopilotScreen` (`components/copilot-screen.tsx`) is the copilot as a full page; mount it as the page.
+
+- **Ask**: the conversation with starter questions (`starterPrompts`), an **Ask about** card (whole workspace, one
+  campaign or one account; changing it (on Enter or leaving the field) starts a fresh conversation) and a **What it can do** card listing the tools
+  and which need approval in graph8. The first message of a session confirms credits. The conversation survives
+  switching tabs.
+- **Team**: every Work channel as a list; opening one (`?id=`, full page with `&view=full`) shows the whole thread: details and the polled conversation with a message box and "ask an agent" (billable, confirmed).
+- **Memory**: add and forget (confirmed) what the copilot remembers.
+- Needs `knowledge:run|read|write|delete` and `work:read|write`. `CopilotPanel` gained `hideTabs` and
+  `starterPrompts`; `CopilotTeamChat` gained `hideChannelPicker`.
+
 Install: `npx @graph8/sdk add copilot` (installs `foundation` first).
 
 ## What you get

package/blocks/copilot/block.json

@@ -26,6 +26,18 @@
     "search_copilot_mentions_copilot_mention_search_post"
   ],
   "components": [
+    {
+      "name": "CopilotScreen",
+      "file": "components/copilot-screen.tsx",
+      "purpose": "Full-page copilot: conversation with starters, ask-about context, tools card, team channel and memory tabs.",
+      "operations": [
+        "list_copilot_tools_copilot_tools_get",
+        "list_work_channels_work_channels_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
     {
       "name": "CopilotPanel",
       "file": "components/copilot-panel.tsx",
@@ -146,6 +158,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }

package/blocks/copilot/components/copilot-panel.tsx

@@ -27,6 +27,7 @@ import { listOf, mentionLabel, summariseReply } from "../lib/copilot-types";
 import type { ChatTurn, CopilotReply, MentionHit } from "../lib/copilot-types";
 import { CopilotMemory } from "./copilot-memory";
 import { CopilotTeamChat } from "./copilot-team-chat";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface CopilotPanelProps {
   /** Where the copilot is being asked from; passed as `canvas_context`. */
@@ -35,6 +36,10 @@ export interface CopilotPanelProps {
   initialTab?: "ask" | "team" | "memory";
   /** Ask for confirmation before every message instead of once per session. */
   confirmEveryMessage?: boolean;
+  /** Hide the Ask / Team / Memory tab bar when the host (for example CopilotScreen) provides its own navigation. */
+  hideTabs?: boolean;
+  /** Example questions shown as buttons in the empty conversation; clicking one fills the message box. */
+  starterPrompts?: string[];
   className?: string;
 }
 
@@ -47,7 +52,8 @@ const mentionsIn = (message: string, list: MentionHit[]): MentionHit[] | undefin
 };
 const MENTION_AT_END = /(^|\s)@([\w.-]{1,40})$/;
 
-export function CopilotPanel({ context, initialTab = "ask", confirmEveryMessage = false, className }: CopilotPanelProps) {
+export function CopilotPanel({ context, initialTab = "ask", confirmEveryMessage = false, hideTabs = false, starterPrompts, className }: CopilotPanelProps) {
+  const brand = useBrand();
   const [tab, setTab] = useState<Tab>(initialTab);
   const [turns, setTurns] = useState<ChatTurn[]>([]);
   const [draft, setDraft] = useState("");
@@ -129,22 +135,25 @@ export function CopilotPanel({ context, initialTab = "ask", confirmEveryMessage
 
   return (
     <div className={`flex h-full min-h-[24rem] flex-col gap-3 ${className ?? ""}`}>
-      <div role="tablist" className="flex gap-1 border-b">
+      {hideTabs ? null : <div role="tablist" className="flex gap-1 border-b">
         {TABS.map((t) => (
           <button key={t.id} role="tab" type="button" aria-selected={tab === t.id} onClick={() => setTab(t.id)}
             className={`px-3 py-2 text-sm ${tab === t.id ? "border-b-2 border-primary font-medium" : "text-muted-foreground"}`}>{t.label}</button>
         ))}
-      </div>
+      </div>}
 
       {tab === "ask" ? (
         <>
           <div className="flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto" aria-live="polite" data-testid="transcript">
-            {turns.length === 0 ? <EmptyState title="Ask the copilot" description="It can look things up, draft copy and propose changes. Type @ to mention a campaign, document or teammate." /> : null}
+            {turns.length === 0 ? (
+              <EmptyState title="Ask the copilot" description="It can look things up, draft copy and propose changes. Type @ to mention a campaign, document or teammate."
+                action={starterPrompts?.length ? <div className="flex flex-wrap justify-center gap-2">{starterPrompts.map((p) => <Button key={p} size="sm" variant="outline" onClick={() => setDraft(p)}>{p}</Button>)}</div> : undefined} />
+            ) : null}
             {turns.map((t) => (
               <div key={t.id} data-testid={`turn-${t.role}`} className={`max-w-[85%] rounded-lg px-3 py-2 text-sm ${t.role === "user" ? "self-end bg-primary text-primary-foreground" : t.error ? "self-start border border-destructive" : "self-start bg-muted"}`}>
                 <p className="whitespace-pre-wrap">{t.text}</p>
                 {t.tools?.length ? <p className="mt-1 text-xs opacity-70">Used: {t.tools.join(", ")}</p> : null}
-                {t.needsApproval?.length ? <p className="mt-1 text-xs text-amber-700">Needs your approval in graph8 before it runs: {t.needsApproval.join(", ")}</p> : null}
+                {t.needsApproval?.length ? <p className="mt-1 text-xs text-amber-700">Needs your approval in {brand.linkLabel} before it runs: {t.needsApproval.join(", ")}</p> : null}
                 {t.sources ? <p className="mt-1 text-xs opacity-70">{t.sources} sources</p> : null}
               </div>
             ))}

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

@@ -0,0 +1,148 @@
+"use client";
+
+/**
+ * CopilotScreen: the graph8 copilot as a full page. Three tabs.
+ *   Ask:    the conversation (CopilotPanel without its own tabs), starter questions, an "Ask about" card that points the
+ *           copilot at the whole workspace, one campaign or one account, and a "What it can do" card listing its tools and
+ *           which need a person's approval in graph8.
+ *   Team:   every Work channel the key can read as a list; opening one (deep link ?id=) shows the whole thread: its details
+ *           and the polled conversation with "ask an agent" and a message box (CopilotTeamChat).
+ *   Memory: what the copilot remembers, add / forget (CopilotMemory).
+ * The Ask conversation stays alive while you visit other tabs.
+ * The first message of a session asks to confirm credits (billable) inside CopilotPanel; forgetting a memory and
+ * posting to an agent are confirmed in their parts.
+ *
+ * SDK operations of its own:
+ *   1. GET /copilot/tools   (copilot.listCopilotTools)   read   the "What it can do" card
+ * Everything else is CopilotPanel / CopilotTeamChat / CopilotMemory (chat, mention search, work channels and
+ * messages, memories). Slot props: toolbarActions, sidebarExtra.
+ */
+import { useState, type ReactNode } from "react";
+import { Sparkles } from "lucide-react";
+import { Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { listOf } from "../lib/copilot-types";
+import type { ToolRow } from "../lib/copilot-types";
+import { CopilotMemory } from "./copilot-memory";
+import { CopilotPanel } from "./copilot-panel";
+import { CopilotTeamChat } from "./copilot-team-chat";
+import type { WorkChannel } from "../lib/copilot-types";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface CopilotScreenProps {
+  /** Starter questions shown in the empty conversation. */
+  starterPrompts?: string[];
+  /** Start with the copilot pointed at this campaign or account. */
+  initialContext?: { mode: "global" | "campaign" | "account"; id?: string };
+  toolbarActions?: ReactNode;
+  sidebarExtra?: ReactNode;
+  className?: string;
+}
+
+const TABS = [{ id: "ask", label: "Ask" }, { id: "team", label: "Team" }, { id: "memory", label: "Memory" }];
+const MODES = [{ id: "global", label: "Everything" }, { id: "campaign", label: "One campaign" }, { id: "account", label: "One account" }] as const;
+const STARTERS = ["Summarise how outbound is doing this month", "Draft a follow-up for a prospect who went quiet", "Which of my campaigns needs attention?"];
+
+function ToolsCard() {
+  const tools = useG8Query((signal) => g8Get("/copilot/tools", undefined, { signal }), []);
+  const rows = listOf<ToolRow>(tools.data, "items");
+  const gated = rows.filter((t) => t.requires_approval || t.needs_approval);
+  return (
+    <SectionCard title="What it can do" description={rows.length ? `${rows.length} tools, ${gated.length} need your approval` : undefined}>
+      {tools.error ? <ApiError error={tools.error} title="Could not load tools" onRetry={() => void tools.refetch()} /> : null}
+      {tools.loading && rows.length === 0 ? <Skeleton className="h-16 w-full" /> : null}
+      <ul className="max-h-64 space-y-2 overflow-y-auto" data-testid="tools">
+        {rows.map((t) => (
+          <li key={t.name} className="flex items-start justify-between gap-2 text-sm">
+            <span><span className="font-medium">{t.name}</span>{t.description ? <span className="block text-xs text-muted-foreground">{t.description}</span> : null}</span>
+            {t.requires_approval || t.needs_approval ? <StatusPill tone="warning">needs approval</StatusPill> : null}
+          </li>
+        ))}
+      </ul>
+    </SectionCard>
+  );
+}
+
+function TeamPane() {
+  const [selected, setSelected] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const close = () => { setSelected(""); setView(""); };
+  const channels = useG8Query((signal) => g8Get("/work/channels", undefined, { signal }), []);
+  const rows = listOf<WorkChannel>(channels.data, "channels");
+  const open = rows.find((c) => c.id === selected);
+  const label = (c: WorkChannel) => c.displayName ?? c.name ?? c.id ?? "Channel";
+  const list = (
+    <div className="flex flex-col gap-2">
+      {channels.error ? <ApiError error={channels.error} title="Could not load channels" onRetry={() => void channels.refetch()} /> : null}
+      {channels.loading && rows.length === 0 ? <Skeleton className="h-14 w-full" /> : null}
+      <ul className="rounded-md border" data-testid="channels">
+        {rows.map((c) => (
+          <li key={c.id} className={c.id === selected ? "bg-accent" : ""}>
+            <button type="button" data-testid={`channel-${c.id}`} onClick={() => setSelected(c.id ?? "")} className="block w-full border-b px-3 py-2 text-left">
+              <span className="block truncate text-sm font-medium">{label(c)}</span>
+              {c.description ? <span className="block truncate text-xs text-muted-foreground">{c.description}</span> : null}
+            </button>
+          </li>
+        ))}
+      </ul>
+      {!channels.loading && !channels.error && rows.length === 0 ? <EmptyState title="No channels" description="Work channels this key may read show up here." /> : null}
+    </div>
+  );
+  const detail = open ? (
+    <DetailPanel title={label(open)} subtitle={open.kind} onClose={close} onExpand={() => setView("full")}
+      tabs={[
+        { id: "conversation", label: "Conversation", content: <CopilotTeamChat key={open.id} channelId={open.id} hideChannelPicker /> },
+        { id: "details", label: "Details", content: <KeyValueList columns={2} items={[{ label: "Name", value: label(open) }, { label: "Kind", value: open.kind }, { label: "Purpose", value: open.description, wide: true }, { label: "Channel id", value: open.id, mono: true }]} /> },
+      ]} />
+  ) : selected && !channels.loading ? <EmptyState title="Channel not found" description="This key may not have a seat in it." /> : null;
+  return <SplitView list={list} detail={detail} detailOpen={Boolean(selected)} onCloseDetail={close} expanded={view === "full"} onExpandedChange={(e) => setView(e ? "full" : "")} detailWidth="xl" />;
+}
+
+export function CopilotScreen({ starterPrompts = STARTERS, initialContext, toolbarActions, sidebarExtra, className }: CopilotScreenProps) {
+  const brand = useBrand();
+  const [tab, setTab] = useUrlState("tab", "ask");
+  const [mode, setMode] = useState<"global" | "campaign" | "account">(initialContext?.mode ?? "global");
+  const [refId, setRefId] = useState(initialContext?.id ?? "");
+  // The id applies on blur or Enter, so typing does not restart the conversation on every keystroke.
+  const [refDraft, setRefDraft] = useState(initialContext?.id ?? "");
+  const current = TABS.some((t) => t.id === tab) ? tab : "ask";
+  const id = refId.trim() || null;
+  const context = { mode, campaignId: mode === "campaign" ? id : null, accountId: mode === "account" ? id : null };
+
+  return (
+    <ScreenLayout className={className} title="Copilot" description={`Ask ${brand.linkLabel} anything about your pipeline, draft with it, and decide what it remembers.`}
+      icon={<Sparkles className="size-5" />} tabs={TABS} activeTab={current}
+      onTabChange={setTab} actions={toolbarActions}>
+      <div className={current === "ask" ? "grid gap-4 lg:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]" : "hidden"}>
+        {/* Keyed on the context so a changed target starts a fresh conversation instead of mixing subjects. */}
+        <CopilotPanel key={`${mode}:${id ?? ""}`} hideTabs initialTab="ask" context={context} starterPrompts={starterPrompts} className="min-h-[32rem] rounded-lg border p-3" />
+        <div className="space-y-4">
+          <SectionCard title="Ask about" description="Changing this starts a new conversation.">
+            <div role="group" aria-label="Ask about" className="flex flex-col gap-2">
+              <select aria-label="Subject" className="h-9 rounded-md border bg-background px-2 text-sm" value={mode} onChange={(e) => { setMode(e.target.value as typeof mode); setRefDraft(""); setRefId(""); }}>
+                {MODES.map((m) => <option key={m.id} value={m.id}>{m.label}</option>)}
+              </select>
+              {mode !== "global" ? (
+                <div className="flex flex-col gap-1"><Label htmlFor="cp-ref">{mode === "campaign" ? "Campaign id" : "Account id"}</Label><Input id="cp-ref" value={refDraft} onChange={(e) => setRefDraft(e.target.value)} onBlur={() => setRefId(refDraft)} onKeyDown={(e) => { if (e.key === "Enter") setRefId(refDraft); }} /></div>
+              ) : null}
+            </div>
+          </SectionCard>
+          <ToolsCard />
+          {sidebarExtra}
+        </div>
+      </div>
+      {current === "team" ? <TeamPane /> : null}
+      {current === "memory" ? <CopilotMemory /> : null}
+    </ScreenLayout>
+  );
+}

package/blocks/copilot/components/copilot-team-chat.tsx

@@ -33,6 +33,8 @@ export interface CopilotTeamChatProps {
   channelId?: string;
   /** Poll interval in ms. Default 4000. */
   pollMs?: number;
+  /** Hide the channel picker when the host (for example CopilotScreen) already chose the channel. */
+  hideChannelPicker?: boolean;
   className?: string;
 }
 
@@ -41,14 +43,14 @@ interface Page { conversation_id?: string; messages?: WorkMessageRow[] }
 
 const newKey = (): string => `team-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 
-export function CopilotTeamChat({ channelId, pollMs = 4000, className }: CopilotTeamChatProps) {
+export function CopilotTeamChat({ channelId, pollMs = 4000, hideChannelPicker, className }: CopilotTeamChatProps) {
   const [channel, setChannel] = useState<string | undefined>(channelId);
   const [text, setText] = useState("");
   const [agentId, setAgentId] = useState("");
   const [confirming, setConfirming] = useState(false);
   const draftKey = useRef(newKey());
 
-  const channels = useG8Query((signal) => g8Get("/work/channels", undefined, { signal }), []);
+  const channels = useG8Query((signal) => g8Get("/work/channels", undefined, { signal }), [], { enabled: !(hideChannelPicker && channelId) });
   const agents = useG8Query((signal) => g8Get("/work/agents", { limit: 50 }, { signal }), []);
   const rows = listOf<WorkChannel>(channels.data, "channels");
   const roster = listOf<AgentRow>(agents.data, "items");
@@ -73,10 +75,10 @@ export function CopilotTeamChat({ channelId, pollMs = 4000, className }: Copilot
   return (
     <div className={`flex min-h-0 flex-1 flex-col gap-3 ${className ?? ""}`}>
       {channels.error ? <ApiError error={channels.error} title="Could not load channels" onRetry={() => void channels.refetch()} /> : null}
-      <select aria-label="Channel" className="h-9 rounded-md border bg-background px-2 text-sm" value={active ?? ""} onChange={(e) => setChannel(e.target.value)}>
+      {hideChannelPicker ? null : <select aria-label="Channel" className="h-9 rounded-md border bg-background px-2 text-sm" value={active ?? ""} onChange={(e) => setChannel(e.target.value)}>
         {rows.map((c) => <option key={c.id} value={c.id}>{c.displayName ?? c.name ?? c.id}</option>)}
-      </select>
-      {!channels.loading && !channels.error && rows.length === 0 ? <EmptyState title="No channels" description="Work channels this key may read show up here." /> : null}
+      </select>}
+      {!hideChannelPicker && !channels.loading && !channels.error && rows.length === 0 ? <EmptyState title="No channels" description="Work channels this key may read show up here." /> : null}
 
       {active ? (
         <>

package/blocks/crm/README.md

@@ -7,6 +7,28 @@ list, the dialer opens a `ContactDetail`), so their props are part of the contra
 
 Install: `npx @graph8/sdk add crm` (installs `foundation` first).
 
+## Screens
+
+Three finished screens compose the parts below into complete workspaces. Each needs no props, deep-links the open record
+(`?id=`), and takes optional slot props so other blocks can add buttons and tabs.
+
+| Screen | What a person can do | Slots |
+|---|---|---|
+| `ContactsScreen` | Search and filter (name, title, seniority, country), sort the loaded page, paginate, open a contact (timeline, notes, tasks, fields), create, edit, delete one or many, import a CSV/Excel file, review and merge duplicates. Locked emails show as Locked. | `renderRowActions(row, { reload })`, `renderDetailActions(contact, { reload })` (`reload` refetches the list and the open record, keeping filters, page, sort and selection), `extraDetailTabs`, `toolbarActions`, `renderBulkActions`, `onOpenCompany`, `listId` |
+| `CompaniesScreen` | Same flow for accounts: filters (name, domain, industry, country), detail with People, Activity, Notes, Tasks, create (domain required), edit, delete, duplicate review. | `renderRowActions(row, { reload })`, `renderDetailActions(company, { reload })`, `extraDetailTabs`, `toolbarActions`, `renderBulkActions`, `onOpenContact` |
+| `TasksScreen` | The workspace-wide task queue: Open / Completed / All, search, priority / type / linked-record filters, tick to complete or reopen, create, edit, delete, bulk complete and delete, overdue marker. | `renderRowActions`, `renderDetailActions`, `toolbarActions`, `defaultRecord`, `onOpenRecord` |
+
+```tsx
+"use client";
+import { ContactsScreen } from "@/components/g8/crm/contacts-screen";
+export default function Page() { return <ContactsScreen />; }
+```
+
+Prerequisites are the block's own (proxy allow-list including `tasks`, scopes in `block.json`). Sorting works on the loaded page only
+(the API has no sort). Deleting (rows, panel, bulk) and merging always ask first. `TasksScreen` links new tasks to a record only when you
+pass `defaultRecord`; otherwise they are standalone. Company import does not exist in the API: importing contacts creates their
+companies from the domain.
+
 ## What you get
 
 | Component | Use it for | Embed props |
@@ -73,6 +95,11 @@ message to a person.
 - `api-key-scopes` (api): the server key has the scopes in `block.json` (`contacts:delete` is needed for bulk merge).
 - `import-size-limit` (app): the proxy caps bodies at 5 MiB; larger files need a raised cap or a server-side import.
 
+## Known limits
+
+- The tasks "Low" priority filter sends `priority=3`. `GET /tasks` takes a single priority value, so historical
+  tasks stored as `4` (also Low) are not matched by that filter; they still show as Low in the list.
+
 ## Defaults the agent can use without asking
 
 | Decision | Default |
@@ -119,4 +146,5 @@ Ask the person: who may delete or merge records (decide it in the proxy's `autho
 | duplicateCounts / listDuplicates / listRecentMerges / getBulkMergeStatus | GET /duplicates... | read | DedupeReview |
 | rejectSuggestion / startBulkMerge / undoMerge | POST /duplicates... | write | DedupeReview |
 | mergeContact / mergeCompany | POST /contacts/{id}/merge, /companies/{id}/merge | destructive | DedupeReview |
+| listAllTasks / getTask / createGlobalTask | GET /tasks, GET /tasks/{task_id}, POST /tasks | read / read / write | TasksScreen |
 | assertContact, assertCompany (+ batch) | PUT /contacts/assert, /companies/assert | write | recipes (`g8.contacts.upsert`) |