@graph8/sdk 0.308.1 → 0.357.0

package/blocks/copilot/README.md

@@ -0,0 +1,99 @@
+# copilot: the graph8 copilot as a panel
+
+Drop an "Ask graph8" side panel into your app. It chats with the copilot (which can look things up, draft
+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.
+
+Install: `npx @graph8/sdk add copilot` (installs `foundation` first).
+
+## What you get
+
+| Component | Use it for | Embed props |
+|---|---|---|
+| `CopilotPanel` | The whole panel: Ask, Team and Memory tabs | `context`, `initialTab`, `confirmEveryMessage` |
+| `CopilotTeamChat` | A Work channel with polled messages and "ask an agent" | `channelId`, `pollMs` |
+| `CopilotMemory` | What the copilot remembers, plus the tool catalog | `scope` |
+
+## The flow, with the ids that pass between steps
+
+1. **Mention** (optional): typing `@name` calls `POST /copilot/mention-search { query, mode }`; the chosen items
+   are sent back unchanged as `mentions` on the chat call.
+2. **Ask**: `POST /copilot/chat { message, conversation_history, mentions, web_search, thinking, research,
+   session_id, canvas_context }` answers `{ response, events }`. `events` has `text`, `tool_start`,
+   `tool_end`, `approval_required`, `error` and a final `done` with `sources`. The panel keeps the
+   conversation and sends it back as `conversation_history` each time.
+3. **Approvals**: a tool that needs a person (publishing a campaign, exporting a list) comes back as an
+   `approval_required` event and is NOT run. The panel shows "needs your approval in graph8"; the API has no
+   operation to approve it, so the person does that in the graph8 app.
+4. **Team**: `GET /work/channels` gives channel `id`s; `GET /work/conversations/{id}/messages?limit=50` is
+   polled (newest first); `POST /work/messages { channel, message, mentionAgentIds }` posts. Mentioning an
+   agent (ids from `GET /work/agents`) starts an agent turn and its answer arrives as a new message.
+5. **Memory**: `GET /copilot/memory?scope=user`, `POST /copilot/memory { content, scope }`,
+   `DELETE /copilot/memory/{memory_id}`. `GET /copilot/tools` lists the tools and which need approval.
+
+```tsx
+"use client";
+import { CopilotPanel } from "@/components/g8/copilot/components/copilot-panel";
+
+export function AskGraph8({ campaignId }: { campaignId: string }) {
+  return <CopilotPanel context={{ mode: "campaign", campaignId }} className="w-[28rem]" />;
+}
+```
+
+(`add` installs under `components/g8/copilot/`, or `src/components/g8/copilot/`; adjust the alias.)
+
+## Tiers and confirmations
+
+- Chat is `billable`: `CopilotPanel` opens `ConfirmSpendDialog` before the first message of a session, with a
+  "Don't ask again this session" choice. Set `confirmEveryMessage` to ask every time. There is no price or
+  balance read, so the dialog states that replies use credits (research the most) instead of a number.
+- Posting in a channel is a write; with an agent mentioned it starts a billable agent turn, so
+  `CopilotTeamChat` confirms that case as `billable`.
+- Forgetting a memory is `destructive` and confirmed.
+- Mention search, listing memories and tools, reading channels are free reads.
+
+## Prerequisites
+
+- `foundation-installed` (app): proxy `allowedPrefixes` include `copilot` and `work`.
+- `api-key-scopes` (api): `knowledge:run|read|write|delete`, `work:read|write`.
+- `credits` (api): a chat answers 402 when the workspace is out of credit; the panel shows the error.
+
+## Defaults the agent can use without asking
+
+| Decision | Default |
+|---|---|
+| Confirmation for chat | once per session |
+| Web search / thinking / deep research | off |
+| Memory scope | `user` |
+
+Ask the person: which Work channels and agents the panel may use (narrow it in the proxy's `authorize`).
+
+## Known limits
+
+- No streaming: a reply appears when it is complete; the panel shows "Thinking..." meanwhile.
+- A key that is not a member of a channel gets 403 on read and post; an organisation key sits in the built-in
+  channels only.
+- The copilot's memory and personal wiki are per person; with an organisation key they are the key's.
+
+## Recipes
+
+| File | Does |
+|---|---|
+| `recipes/ask-the-copilot.ts` | Ask, read `response` and tool events, handle 402, list the tool catalog |
+| `recipes/remember-and-recall.ts` | Add a memory, list, forget by id |
+| `recipes/post-in-a-work-channel.ts` | Post with an agent mention and poll for the reply |
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| chatWithCopilot | POST /copilot/chat | billable | CopilotPanel |
+| listCopilotMemories | GET /copilot/memory | read | CopilotMemory |
+| createCopilotMemory | POST /copilot/memory | write | CopilotMemory |
+| deleteCopilotMemory | DELETE /copilot/memory/{memory_id} | destructive | CopilotMemory |
+| searchCopilotMentions | POST /copilot/mention-search | read | CopilotPanel |
+| listCopilotTools | GET /copilot/tools | read | CopilotMemory |
+| listWorkAgents | GET /work/agents | read | CopilotTeamChat |
+| listWorkChannels | GET /work/channels | read | CopilotTeamChat |
+| listWorkConversationMessages | GET /work/conversations/{conversation_id}/messages | read | CopilotTeamChat |
+| createWorkMessage | POST /work/messages | write | CopilotTeamChat |

package/blocks/copilot/block.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "copilot",
+  "title": "Copilot",
+  "summary": "A copilot side panel: ask the graph8 copilot (request/response, billable), chat in a Work channel with agents (polled), and manage what it remembers.",
+  "features": [
+    "chat with @mentions, web search, thinking and deep research options",
+    "tool events and approval-needed proposals shown inline",
+    "Work channel chat with agent mentions, polled",
+    "memory list with add and forget",
+    "tool catalog showing which tools need approval"
+  ],
+  "dependsOn": [
+    "foundation"
+  ],
+  "operations": [
+    "chat_with_copilot_copilot_chat_post",
+    "create_copilot_memory_copilot_memory_post",
+    "create_work_message_work_messages_post",
+    "delete_copilot_memory_copilot_memory__memory_id__delete",
+    "list_copilot_memories_copilot_memory_get",
+    "list_copilot_tools_copilot_tools_get",
+    "list_work_agents_work_agents_get",
+    "list_work_channels_work_channels_get",
+    "list_work_conversation_messages_work_conversations__conversation_id__messages_get",
+    "search_copilot_mentions_copilot_mention_search_post"
+  ],
+  "components": [
+    {
+      "name": "CopilotPanel",
+      "file": "components/copilot-panel.tsx",
+      "purpose": "The copilot as a panel: Ask (billable chat with mentions and options), Team and Memory tabs.",
+      "operations": [
+        "search_copilot_mentions_copilot_mention_search_post",
+        "chat_with_copilot_copilot_chat_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "CopilotTeamChat",
+      "file": "components/copilot-team-chat.tsx",
+      "purpose": "A Work channel: read the polled conversation, post, and ask an agent by mention (billable agent turn confirmed).",
+      "operations": [
+        "list_work_channels_work_channels_get",
+        "list_work_agents_work_agents_get",
+        "list_work_conversation_messages_work_conversations__conversation_id__messages_get",
+        "create_work_message_work_messages_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "CopilotMemory",
+      "file": "components/copilot-memory.tsx",
+      "purpose": "What the copilot remembers: list, add, forget (confirmed), plus the tool catalog.",
+      "operations": [
+        "list_copilot_memories_copilot_memory_get",
+        "create_copilot_memory_copilot_memory_post",
+        "delete_copilot_memory_copilot_memory__memory_id__delete",
+        "list_copilot_tools_copilot_tools_get"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/copilot-types.ts",
+      "purpose": "Chat turn and event shapes, and summariseReply(), which folds the copilot's events into one bubble."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/ask-the-copilot.ts",
+      "title": "Ask the copilot and read its answer and tool events",
+      "when": "Server-side copilot calls; billable, answered in one piece."
+    },
+    {
+      "file": "recipes/remember-and-recall.ts",
+      "title": "Teach the copilot a standing fact, forget it",
+      "when": "A rule should shape every answer."
+    },
+    {
+      "file": "recipes/post-in-a-work-channel.ts",
+      "title": "Post in a Work channel, ask an agent, poll for the reply",
+      "when": "Asking a teammate or agent in a shared channel."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "foundation-installed",
+      "description": "The foundation block is installed and the /api/g8 proxy allows the copilot and work prefixes.",
+      "where": "app",
+      "verify": "allowedPrefixes includes \"copilot\" and \"work\"."
+    },
+    {
+      "id": "api-key-scopes",
+      "description": "The API key carries the block's scopes (knowledge and work).",
+      "where": "api",
+      "verify": "describeCurrentKey lists knowledge:run, knowledge:read, knowledge:write, knowledge:delete, work:read, work:write."
+    },
+    {
+      "id": "credits",
+      "description": "The workspace has credits: chat replies are billable and answer 402 when it is out.",
+      "where": "api",
+      "verify": "A test message to the copilot answers 200, not 402."
+    }
+  ],
+  "scopes": [
+    "knowledge:delete",
+    "knowledge:read",
+    "knowledge:run",
+    "knowledge:write",
+    "work:read",
+    "work:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Confirmation for chat",
+      "default": "once per session, with a 'don't ask again' choice (confirmEveryMessage turns it off)",
+      "askHuman": false
+    },
+    {
+      "decision": "Web search, thinking, deep research",
+      "default": "all off",
+      "askHuman": false
+    },
+    {
+      "decision": "Memory scope",
+      "default": "user",
+      "askHuman": false
+    },
+    {
+      "decision": "Which Work channels and agents the panel may use",
+      "default": "whatever the key can read; narrow it in the proxy's authorize hook",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

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

@@ -0,0 +1,87 @@
+"use client";
+
+/**
+ * CopilotMemory: what the copilot remembers about you and your work, and what it can do.
+ *
+ * SDK operations, in order:
+ *   1. listCopilotMemories  GET    /copilot/memory?scope&limit            (read)
+ *   2. createCopilotMemory  POST   /copilot/memory { content, scope }     (write)
+ *   3. deleteCopilotMemory  DELETE /copilot/memory/{memory_id}            (destructive, ConfirmSpendDialog)
+ *   4. listCopilotTools     GET    /copilot/tools                         (read)  which tools exist and which need approval
+ *
+ * A memory is a short fact in plain words ("We never discount below 15%"). The copilot reads memories on
+ * every chat, so a wrong one steers every answer: forgetting one is confirmed.
+ */
+
+import { useState } from "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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { listOf } from "../lib/copilot-types";
+import type { MemoryRow, ToolRow } from "../lib/copilot-types";
+
+export interface CopilotMemoryProps {
+  /** Memory scope to read and write. Default "user". */
+  scope?: string;
+  className?: string;
+}
+
+const idOf = (m: MemoryRow): string => m.memory_id ?? m.id ?? "";
+
+export function CopilotMemory({ scope = "user", className }: CopilotMemoryProps) {
+  const [note, setNote] = useState("");
+  const [forgetting, setForgetting] = useState<MemoryRow | null>(null);
+  const [showTools, setShowTools] = useState(false);
+
+  const memories = useG8Query((signal) => g8Get("/copilot/memory", { scope, limit: 100 }, { signal }), [scope]);
+  const tools = useG8Query((signal) => g8Get("/copilot/tools", undefined, { signal }), [], { enabled: showTools });
+  const add = useG8Mutation(() => g8Post("/copilot/memory", { content: note.trim(), scope }), { onSuccess: () => { setNote(""); void memories.refetch(); } });
+  const forget = useG8Mutation((id: string) => g8Delete(`/copilot/memory/${id}`), { onSuccess: () => { setForgetting(null); void memories.refetch(); } });
+
+  const rows = listOf<MemoryRow>(memories.data, "items");
+  const toolRows = listOf<ToolRow>(tools.data, "items");
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <form className="flex gap-2" onSubmit={(e) => { e.preventDefault(); if (note.trim()) void add.mutate(undefined); }}>
+        <Input aria-label="New memory" placeholder="Something the copilot should always remember" value={note} onChange={(e) => setNote(e.target.value)} />
+        <Button type="submit" loading={add.loading} disabled={!note.trim()}>Remember</Button>
+      </form>
+      {add.error ? <ApiError error={add.error} title="Could not save the memory" /> : null}
+      {memories.error ? <ApiError error={memories.error} title="Could not load memories" onRetry={() => void memories.refetch()} /> : null}
+      {memories.loading && rows.length === 0 ? <Skeleton className="h-10 w-full" /> : null}
+      <ul className="divide-y rounded-md border">
+        {rows.map((m) => (
+          <li key={idOf(m)} data-testid={`memory-${idOf(m)}`} className="flex items-start justify-between gap-3 p-2 text-sm">
+            <span className="whitespace-pre-wrap">{m.content}</span>
+            <Button size="sm" variant="ghost" onClick={() => setForgetting(m)}>Forget</Button>
+          </li>
+        ))}
+      </ul>
+      {!memories.loading && !memories.error && rows.length === 0 ? <EmptyState title="Nothing remembered yet" description="Add the rules and facts you want in every answer." /> : null}
+      {forget.error ? <ApiError error={forget.error} title="Could not forget it" /> : null}
+
+      <div>
+        <Button size="sm" variant="outline" onClick={() => setShowTools((v) => !v)}>{showTools ? "Hide tools" : "What can it do?"}</Button>
+        {tools.error ? <ApiError error={tools.error} title="Could not load tools" onRetry={() => void tools.refetch()} /> : null}
+        {showTools ? (
+          <ul className="mt-2 divide-y rounded-md border" data-testid="tools">
+            {toolRows.map((t) => (
+              <li key={t.name} className="flex items-start justify-between gap-3 p-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 ? <span className="text-xs text-amber-700">needs approval</span> : null}
+              </li>
+            ))}
+          </ul>
+        ) : null}
+      </div>
+
+      <ConfirmSpendDialog open={forgetting != null} tier="destructive" title="Forget this memory" description={forgetting?.content} confirmLabel="Forget"
+        affected={1} confirming={forget.loading} onConfirm={() => forgetting && void forget.mutate(idOf(forgetting))} onCancel={() => setForgetting(null)} />
+    </div>
+  );
+}

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

@@ -0,0 +1,189 @@
+"use client";
+
+/**
+ * CopilotPanel: the graph8 copilot as a side panel. Four tabs: Ask (chat with the copilot), Team (post in a
+ * Work channel and read the answers), Memory (what the copilot remembers, add / forget) and Tools (what it
+ * can do, and which tools need a person's approval).
+ *
+ * Ask, SDK operations in order:
+ *   1. searchCopilotMentions  POST /copilot/mention-search { query, mode }   (read)   as you type "@name"
+ *   2. chatWithCopilot        POST /copilot/chat { message, conversation_history, mentions, web_search, thinking, research, session_id }
+ *                             (billable, ConfirmSpendDialog)  answers { response, events } in one piece: no streaming
+ *
+ * The first message of a session asks for confirmation (every reply spends credits, `research` the most);
+ * "Don't ask again this session" skips it for the rest. Tools that need approval are PROPOSED in `events`
+ * and shown as "needs approval"; the API cannot approve them, the person does that in the graph8 app.
+ * Team and Memory are CopilotTeamChat and CopilotMemory; mount them alone if you only need one.
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { Button, Switch, 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 { g8Post } from "@/g8/lib/g8-client";
+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";
+
+export interface CopilotPanelProps {
+  /** Where the copilot is being asked from; passed as `canvas_context`. */
+  context?: { mode?: "global" | "campaign" | "account"; campaignId?: string | null; accountId?: string | null };
+  /** First tab. Default "ask". */
+  initialTab?: "ask" | "team" | "memory";
+  /** Ask for confirmation before every message instead of once per session. */
+  confirmEveryMessage?: boolean;
+  className?: string;
+}
+
+type Tab = "ask" | "team" | "memory";
+const TABS: Array<{ id: Tab; label: string }> = [{ id: "ask", label: "Ask" }, { id: "team", label: "Team" }, { id: "memory", label: "Memory" }];
+/** Only mentions whose @label is still in the text go to the API (the person may have deleted it). */
+const mentionsIn = (message: string, list: MentionHit[]): MentionHit[] | undefined => {
+  const kept = list.filter((m) => message.includes(`@${mentionLabel(m)}`));
+  return kept.length ? kept : undefined;
+};
+const MENTION_AT_END = /(^|\s)@([\w.-]{1,40})$/;
+
+export function CopilotPanel({ context, initialTab = "ask", confirmEveryMessage = false, className }: CopilotPanelProps) {
+  const [tab, setTab] = useState<Tab>(initialTab);
+  const [turns, setTurns] = useState<ChatTurn[]>([]);
+  const [draft, setDraft] = useState("");
+  const [mentions, setMentions] = useState<MentionHit[]>([]);
+  const [options, setOptions] = useState({ web_search: false, thinking: false, research: false });
+  const [sessionId, setSessionId] = useState<string | undefined>();
+  const [pending, setPending] = useState<string | null>(null);
+  const [skipConfirm, setSkipConfirm] = useState(false);
+  const [suggestions, setSuggestions] = useState<MentionHit[]>([]);
+  const nextId = useRef(1);
+  const lastMentions = useRef<MentionHit[]>([]);
+  const [dontAsk, setDontAsk] = useState(false);
+  const bottom = useRef<HTMLDivElement>(null);
+
+  const searchSeq = useRef(0);
+  // Latest request wins: a slow answer for "@ac" must not overwrite the one for "@acme".
+  const search = useG8Mutation(async (q: string) => {
+    const mine = ++searchSeq.current;
+    const res = await g8Post("/copilot/mention-search", { query: q, mode: context?.mode });
+    if (mine === searchSeq.current) setSuggestions(listOf<MentionHit>(res, "items"));
+    return res;
+  });
+  const chat = useG8Mutation(
+    (v: { message: string; history: ChatTurn[]; mentions: MentionHit[] }) =>
+      g8Post<CopilotReply>("/copilot/chat", {
+        message: v.message, conversation_history: v.history.filter((t) => !t.error).map((t) => ({ role: t.role, content: t.text })),
+        mentions: mentionsIn(v.message, v.mentions), session_id: sessionId,
+        canvas_context: context ? { mode: context.mode ?? "global", campaignId: context.campaignId ?? null, accountId: context.accountId ?? null } : undefined,
+        web_search: options.web_search, thinking: options.thinking, research: options.research,
+      }),
+    {
+      onSuccess: (res) => {
+        const reply = ((res as { data?: CopilotReply }).data ?? res) as CopilotReply;
+        if (reply.session_id) setSessionId(reply.session_id);
+        setTurns((t) => [...t, summariseReply(reply, nextId.current++)]);
+      },
+    },
+  );
+
+  useEffect(() => { bottom.current?.scrollIntoView?.({ block: "end" }); }, [turns.length, chat.loading]);
+  useEffect(() => {
+    const m = MENTION_AT_END.exec(draft);
+    if (!m) { searchSeq.current++; setSuggestions([]); return; }
+    const t = setTimeout(() => void search.mutate(m[2]), 200);
+    return () => clearTimeout(t);
+  }, [draft]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const send = (text: string, history: ChatTurn[] = turns, sent: MentionHit[] = mentions) => {
+    setPending(null);
+    lastMentions.current = sent;
+    setTurns((t) => [...t, { id: nextId.current++, role: "user", text }]);
+    setDraft("");
+    void chat.mutate({ message: text, history, mentions: sent });
+    setMentions([]);
+  };
+  // Retry: the failed user turn is not part of the history it is resent with, mentions are kept, and the billable
+  // confirmation applies exactly as for a new message.
+  const retry = () => {
+    const last = turns[turns.length - 1];
+    if (last?.role !== "user") return;
+    const base = turns.slice(0, -1);
+    setTurns(base);
+    chat.reset();
+    if (skipConfirm && !confirmEveryMessage) send(last.text, base, lastMentions.current);
+    else { setMentions(lastMentions.current); setPending(last.text); }
+  };
+  const submit = () => {
+    const text = draft.trim();
+    if (!text || chat.loading) return;
+    if (skipConfirm && !confirmEveryMessage) send(text);
+    else setPending(text);
+  };
+  const pick = (m: MentionHit) => {
+    setMentions((list) => [...list, m]);
+    setDraft((d) => d.replace(MENTION_AT_END, (_all, lead: string) => `${lead}@${mentionLabel(m)} `));
+    setSuggestions([]);
+  };
+  const setOpt = (k: keyof typeof options) => (v: boolean) => setOptions((o) => ({ ...o, [k]: v }));
+
+  return (
+    <div className={`flex h-full min-h-[24rem] flex-col gap-3 ${className ?? ""}`}>
+      <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>
+
+      {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.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.sources ? <p className="mt-1 text-xs opacity-70">{t.sources} sources</p> : null}
+              </div>
+            ))}
+            {chat.loading ? <div className="self-start rounded-lg bg-muted px-3 py-2 text-sm text-muted-foreground">Thinking...</div> : null}
+            {chat.error ? <ApiError error={chat.error} title="The copilot could not answer" onRetry={retry} /> : null}
+            <div ref={bottom} />
+          </div>
+
+          <div className="flex flex-wrap items-center gap-4 text-xs">
+            {([["web_search", "Web search"], ["thinking", "Think longer"], ["research", "Deep research"]] as const).map(([k, label]) => (
+              <label key={k} className="flex items-center gap-1"><Switch aria-label={label} checked={options[k]} onCheckedChange={setOpt(k)} />{label}</label>
+            ))}
+            {mentions.length ? <span className="text-muted-foreground">Mentioning: {mentions.map(mentionLabel).join(", ")}</span> : null}
+          </div>
+          {suggestions.length ? (
+            <ul role="listbox" aria-label="Mentions" className="rounded-md border bg-background text-sm">
+              {suggestions.map((m, i) => (
+                <li key={`${m.id ?? i}`}><button type="button" role="option" aria-selected={false} className="w-full px-3 py-1 text-left hover:bg-accent" onClick={() => pick(m)}>{mentionLabel(m)}{m.type ? <span className="ml-2 text-xs text-muted-foreground">{m.type}</span> : null}</button></li>
+              ))}
+            </ul>
+          ) : null}
+          <div className="flex gap-2">
+            <Textarea aria-label="Message" rows={2} placeholder="Ask anything" value={draft} onChange={(e) => setDraft(e.target.value)}
+              onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); submit(); } }} />
+            <Button className="self-end" disabled={!draft.trim() || chat.loading} onClick={submit}>Send</Button>
+          </div>
+        </>
+      ) : null}
+      {tab === "team" ? <CopilotTeamChat /> : null}
+      {tab === "memory" ? <CopilotMemory /> : null}
+
+      <ConfirmSpendDialog open={pending != null} tier="billable" title="Send to the copilot"
+        description={
+          <div className="flex flex-col gap-2">
+            <span>Each reply uses credits. Web search and thinking use more; deep research uses the most.</span>
+            <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={dontAsk} onChange={(e) => setDontAsk(e.target.checked)} />Don&apos;t ask again this session</label>
+          </div>
+        }
+        confirmLabel="Send" onConfirm={() => { if (pending) { setSkipConfirm(dontAsk); send(pending); } }} onCancel={() => { setPending(null); setDontAsk(false); }} />
+    </div>
+  );
+}

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

@@ -0,0 +1,111 @@
+"use client";
+
+/**
+ * CopilotTeamChat: a Work channel inside the panel. Read the conversation, post a message, and @-ask an
+ * agent: mentioning an agent starts an agent turn in the background, so the answer arrives as a new
+ * message a moment later. There are no streams, so the conversation is polled.
+ *
+ * SDK operations, in order:
+ *   1. listWorkChannels             GET  /work/channels                                  (read)
+ *   2. listWorkAgents               GET  /work/agents                                    (read)  who can be asked
+ *   3. listWorkConversationMessages GET  /work/conversations/{conversation_id}/messages?limit  (read)  polled; newest first
+ *   4. createWorkMessage            POST /work/messages { channel, message, mentionAgentIds }   (write; with an agent
+ *                                   mentioned it starts a billable agent turn, so it goes through ConfirmSpendDialog)
+ *
+ * A key may only post where it holds a seat (the built-in channels for an organisation key): a 403 is shown
+ * as-is. The conversation id is the channel's `id`.
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { Button, Input } 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 { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/copilot-types";
+import type { WorkChannel, WorkMessageRow } from "../lib/copilot-types";
+
+export interface CopilotTeamChatProps {
+  /** Start in this channel (id). Without it the first channel is opened. */
+  channelId?: string;
+  /** Poll interval in ms. Default 4000. */
+  pollMs?: number;
+  className?: string;
+}
+
+interface AgentRow { agent_id?: string | null; name?: string | null }
+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) {
+  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 agents = useG8Query((signal) => g8Get("/work/agents", { limit: 50 }, { signal }), []);
+  const rows = listOf<WorkChannel>(channels.data, "channels");
+  const roster = listOf<AgentRow>(agents.data, "items");
+  const active = channel ?? rows[0]?.id ?? undefined;
+
+  const feed = useJobPoll<Page>((signal) => g8Get(`/work/conversations/${active}/messages`, { limit: 50 }, { signal }).then((r) => bodyOf<Page>(r)), {
+    enabled: Boolean(active), isTerminal: () => false, intervalMs: pollMs, backoff: 1, maxAttempts: 100000,
+  });
+  useEffect(() => { if (active) feed.start(); }, [active]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const post = useG8Mutation(
+    // One key per draft: a double submit or a retry of the same draft is the same post, not a second one.
+    () => g8Post("/work/messages", { channel: active, message: text.trim(), mentionAgentIds: agentId ? [agentId] : undefined }, { idempotencyKey: draftKey.current }),
+    { onSuccess: () => { setText(""); setConfirming(false); draftKey.current = newKey(); feed.start(); }, onError: () => setConfirming(false) },
+  );
+  const submit = () => post.loading ? undefined : (agentId ? setConfirming(true) : void post.mutate(undefined));
+  // After a channel switch the previous channel's page is still in state until the first poll lands: do not show it.
+  const stale = Boolean(feed.status?.conversation_id && feed.status.conversation_id !== active);
+  const messages = stale ? [] : [...(feed.status?.messages ?? [])].reverse();
+  const agentName = roster.find((a) => a.agent_id === agentId)?.name ?? "the agent";
+
+  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)}>
+        {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}
+
+      {active ? (
+        <>
+          {feed.error ? <ApiError error={feed.error} title="Could not load the conversation" onRetry={() => feed.start()} /> : null}
+          <ul className="flex min-h-0 flex-1 flex-col gap-2 overflow-y-auto" data-testid="messages">
+            {messages.map((m, i) => (
+              <li key={m.id ?? i} className="rounded-md bg-muted px-3 py-2 text-sm">
+                <span className="mr-2 text-xs font-medium">{m.author?.displayName ?? m.author?.name ?? "Someone"}</span>
+                <span className="whitespace-pre-wrap">{m.text}</span>
+              </li>
+            ))}
+          </ul>
+          {!feed.status && !feed.error ? <p className="text-sm text-muted-foreground">Loading...</p> : null}
+          {feed.status && !stale && messages.length === 0 ? <p className="text-sm text-muted-foreground">No messages yet.</p> : null}
+          {post.error ? <ApiError error={post.error} title="Could not post" /> : null}
+          <div className="flex gap-2">
+            <select aria-label="Ask an agent" className="h-9 w-40 rounded-md border bg-background px-2 text-sm" value={agentId} onChange={(e) => setAgentId(e.target.value)}>
+              <option value="">No agent</option>
+              {roster.map((a) => a.agent_id ? <option key={a.agent_id} value={a.agent_id}>{a.name ?? a.agent_id}</option> : null)}
+            </select>
+            <Input aria-label="Team message" placeholder="Write a message" value={text} onChange={(e) => setText(e.target.value)}
+              onKeyDown={(e) => { if (e.key === "Enter" && text.trim() && !post.loading) submit(); }} />
+            <Button loading={post.loading} disabled={!text.trim()} onClick={submit}>Post</Button>
+          </div>
+        </>
+      ) : null}
+
+      <ConfirmSpendDialog open={confirming} tier="billable" title={`Ask ${agentName}`} description="Mentioning an agent starts an agent turn that uses credits. Your message is posted for the whole channel to see."
+        confirmLabel="Post and ask" confirming={post.loading} onConfirm={() => void post.mutate(undefined)} onCancel={() => setConfirming(false)} />
+    </div>
+  );
+}