@graph8/sdk 0.370.0 → 0.374.0

package/blocks/company-intelligence/lib/intelligence-types.ts

@@ -0,0 +1,230 @@
+"use client";
+
+/**
+ * Shapes and helpers for the company-intelligence components.
+ *
+ * Reality of this API (read from the handlers, not assumed): intelligence is the research graph8 runs on YOUR OWN website
+ * (the workspace's primary website). Every response is an open payload, so each field below is optional and read
+ * defensively; a missing value is shown as unknown (a dash), never as a guess and never as 0.
+ *
+ * SDK operations: none (types and pure helpers).
+ */
+
+export type Rec = Record<string, unknown>;
+
+export const isRec = (v: unknown): v is Rec => v != null && typeof v === "object" && !Array.isArray(v);
+export const asArray = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
+
+/** A non-empty string (numbers are formatted), else null. */
+export function text(v: unknown): string | null {
+  if (typeof v === "string") return v.trim() ? v.trim() : null;
+  if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  return null;
+}
+
+export function num(v: unknown): number | null {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+/** Read a body that may or may not be wrapped in `{ data }`. */
+export function intelBody<T>(env: unknown): T {
+  const e = env as { data?: unknown } | null;
+  return (e && typeof e === "object" && "data" in e && e.data != null ? e.data : env) as T;
+}
+
+/** The rows of a list payload: a bare array, `{ items }`, or a named key (`documents`, `reports`). */
+export function rowsOf<T = Rec>(payload: unknown, ...keys: string[]): T[] {
+  if (Array.isArray(payload)) return payload as T[];
+  if (!isRec(payload)) return [];
+  for (const k of ["items", ...keys]) if (Array.isArray(payload[k])) return payload[k] as T[];
+  return [];
+}
+
+/** A host as a person types it: strips the scheme, www., port-less path and query. `https://www.Acme.com/x` -> `acme.com`. */
+export function canonicalDomain(input: string | null | undefined): string {
+  return (input ?? "").trim().toLowerCase().replace(/^https?:\/\//, "").replace(/^www\./, "").split(/[/?#]/)[0];
+}
+
+/** http(s) URLs only: the API puts web content in these payloads, and a `javascript:` URL would run on click. */
+export function safeHttpUrl(value: unknown): string | null {
+  const s = text(value);
+  if (!s || !/^https?:\/\/[^\s/]+/i.test(s)) return null;
+  try {
+    const u = new URL(s);
+    return u.protocol === "http:" || u.protocol === "https:" ? u.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+export function humanize(key: string): string {
+  const s = key.replace(/[_-]+/g, " ").trim();
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : key;
+}
+
+/** A key as a title: `brand_sentiment` -> `Brand Sentiment`, matching the display names the API gives collected sources. */
+export function titleize(key: string): string {
+  return key.replace(/[_-]+/g, " ").trim().replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+export function when(v: unknown): string | null {
+  const s = text(v);
+  if (!s) return null;
+  const d = new Date(s);
+  return Number.isNaN(d.getTime()) ? s : d.toLocaleString();
+}
+
+/** Date part only, in UTC, so the same instant reads the same in every time zone. */
+export function whenDate(v: unknown): string | null {
+  const s = text(v);
+  if (!s) return null;
+  const d = new Date(s);
+  return Number.isNaN(d.getTime()) ? s : d.toLocaleDateString(undefined, { timeZone: "UTC" });
+}
+
+// ---- research run (intelligence) -------------------------------------------------------------------------------------
+
+export interface RunStatus {
+  task_id?: string;
+  status?: string;
+  progress?: number;
+  current_step?: string | null;
+  steps?: Record<string, string | null>;
+  website_url?: string;
+  created_at?: string | null;
+  completed_at?: string | null;
+  error_message?: string | null;
+}
+
+export interface LatestTask { task_id?: string; website_url?: string | null; status?: string; created_at?: string | null; completed_at?: string | null }
+
+export interface AnalyzeAccepted { task_id?: string; message?: string; website_url?: string; domain_sync_warning?: string | null }
+
+export interface IntelDocument {
+  id?: string;
+  data_type: string;
+  display_name?: string | null;
+  folder?: string | null;
+  website_url?: string | null;
+  status?: string | null;
+  collected_at?: string | null;
+}
+
+/** A run is final once it stops pending or running. */
+export const isRunFinal = (status: string | undefined | null): boolean => status != null && status !== "pending" && status !== "running" && status !== "in_progress";
+
+/** The steps of a run, in the order the API lists them, with their state. */
+export function runSteps(run: RunStatus | undefined): Array<{ key: string; label: string; state: string }> {
+  return Object.entries(run?.steps ?? {}).map(([key, state]) => ({ key, label: humanize(key), state: state ?? "pending" }));
+}
+
+export const stepTone = (state: string): "positive" | "negative" | "info" | "neutral" =>
+  state === "completed" ? "positive" : state === "failed" ? "negative" : state === "running" || state === "in_progress" ? "info" : "neutral";
+
+/** True when a run finished less than an hour ago: the API answers a repeat request with that run and charges nothing (no `force`). */
+export function finishedWithinHour(task: LatestTask | null | undefined, now = Date.now()): boolean {
+  const at = task?.completed_at ? Date.parse(task.completed_at) : NaN;
+  return task?.status === "completed" && Number.isFinite(at) && now - at < 3_600_000 && now - at >= 0;
+}
+
+// ---- the six research reports ----------------------------------------------------------------------------------------
+
+/** The report types the retry operation accepts (its request enum, copied from the contract), by report number 1 to 6. */
+export const REPORT_TYPES = ["review_sentiment", "competitive_teardown", "voice_of_customer", "gtm_channel", "analyst_media", "buyer_psychology"] as const;
+export type ReportType = (typeof REPORT_TYPES)[number];
+
+export interface ReportSlot {
+  id: string | null;
+  report_number: number;
+  report_type: string;
+  report_title?: string | null;
+  status: string;
+  has_content?: boolean;
+  approved?: boolean;
+  created_at?: string | null;
+  started_at?: string | null;
+  completed_at?: string | null;
+}
+
+export interface WorkflowStatus {
+  website_url?: string;
+  workflow_status?: string;
+  reports_completed?: number;
+  total_reports?: number;
+  current_report?: string | null;
+  reports?: Record<string, ReportSlot>;
+  started_at?: string | null;
+  completed_at?: string | null;
+}
+
+/** The six slots in report order. `reports` is keyed `report_1`..`report_6`. */
+export function slotsOf(w: WorkflowStatus | undefined): ReportSlot[] {
+  const map = w?.reports ?? {};
+  return Object.keys(map).sort((a, b) => Number(a.replace(/\D/g, "")) - Number(b.replace(/\D/g, ""))).map((k) => map[k]);
+}
+
+export const isGenerating = (status: string | undefined | null): boolean => status === "generating" || status === "in_progress";
+export const isReportDone = (status: string | undefined | null): boolean => status === "completed" || status === "approved";
+
+/** Reports a workflow resume would generate: every slot that is not finished and is not already running. */
+export function incompleteSlots(slots: ReportSlot[]): ReportSlot[] {
+  return slots.filter((s) => !isReportDone(s.status) && !isGenerating(s.status));
+}
+
+export interface ReportDetailBody {
+  id?: string;
+  report_title?: string | null;
+  report_type?: string;
+  report_number?: number;
+  website_url?: string;
+  status?: string;
+  markdown_content?: string | null;
+  error_message?: string | null;
+  approved?: boolean;
+  approved_at?: string | null;
+  estimated_cost_usd?: number | null;
+  credits_used?: number | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+  completed_at?: string | null;
+}
+
+/** What the report used the last time it ran: a real number from the report itself, or null when the API did not say. */
+export function lastRunCredits(r: ReportDetailBody | undefined): number | null {
+  const v = num(r?.credits_used) ?? num(r?.estimated_cost_usd);
+  return v != null && v > 0 ? v : null;
+}
+
+/**
+ * The PATCH body for an edited report: only what changed. Clearing the text sends "" (the API only ignores null).
+ * Returns null when nothing changed.
+ */
+export function reportEdit(original: string | null | undefined, draft: string): { markdown_content: string } | null {
+  return (original ?? "") === draft ? null : { markdown_content: draft };
+}
+
+export interface ThinkingEvent { type?: string; timestamp?: string; data?: Rec | null }
+
+/** One readable line for a recorded reasoning event, from the fields the stream writes (`message`, tool name, error). */
+export function eventLine(e: ThinkingEvent): string {
+  const d = isRec(e.data) ? e.data : {};
+  return text(d.message) ?? text(d.tool) ?? text(d.tool_name) ?? text(d.error) ?? text(d.status) ?? humanize(e.type ?? "event");
+}
+
+// ---- wiki (global context) documents ---------------------------------------------------------------------------------
+
+export interface WikiDoc {
+  id: string;
+  file_type?: string | null;
+  display_name?: string | null;
+  category?: string | null;
+  folder_path?: string | null;
+  status?: string | null;
+  version?: number | null;
+  content?: string | null;
+  credits_used?: number | null;
+  updated_at?: string | null;
+  is_done?: boolean;
+}
+
+export const docTitle = (d: Pick<WikiDoc, "display_name" | "file_type" | "id">): string => text(d.display_name) ?? (d.file_type ? humanize(d.file_type) : d.id);

package/blocks/company-intelligence/lib/safe-markdown.tsx

@@ -0,0 +1,150 @@
+"use client";
+
+/**
+ * SafeMarkdown: renders the markdown the API returns (research reports, wiki documents) without ever turning it into HTML.
+ * Every piece of text becomes a React text node, so raw HTML, `<script>`, event handlers and `javascript:` links in a
+ * report show up as plain text instead of running. Links are drawn only for http(s) URLs (with `rel="noopener noreferrer"`);
+ * images are not drawn, they stay as their text. No `dangerouslySetInnerHTML` anywhere.
+ *
+ * Supported: headings, paragraphs, bullet and numbered lists, block quotes, fenced code, horizontal rules, pipe tables,
+ * and inline bold, italic, code and links. Anything else is a paragraph of plain text.
+ *
+ * SDK operations: none.
+ */
+import type { ReactNode } from "react";
+import { cn } from "@graph8/sdk/ui";
+import { safeHttpUrl } from "./intelligence-types";
+
+// Underscore emphasis only at word edges, so snake_case_names are left alone.
+const INLINE = /(\*\*([^*]+)\*\*|(?<!\w)__([^_]+)__(?!\w)|`([^`]+)`|\[([^\]]+)\]\(([^)\s]+)\)|\*([^*\s][^*]*)\*|(?<!\w)_([^_\s][^_]*)_(?!\w))/g;
+
+/** Inline markup to React nodes. Unsafe link targets keep their text and lose the link. */
+export function renderInline(source: string, keyPrefix = "i"): ReactNode[] {
+  const out: ReactNode[] = [];
+  let last = 0;
+  let n = 0;
+  for (const m of source.matchAll(INLINE)) {
+    const at = m.index ?? 0;
+    if (at > last) out.push(source.slice(last, at));
+    const key = `${keyPrefix}${n++}`;
+    if (m[2] ?? m[3]) out.push(<strong key={key}>{m[2] ?? m[3]}</strong>);
+    else if (m[4]) out.push(<code key={key} className="rounded bg-muted px-1 py-0.5 text-[0.9em]">{m[4]}</code>);
+    else if (m[5]) {
+      const href = safeHttpUrl(m[6]);
+      out.push(href ? <a key={key} href={href} target="_blank" rel="noopener noreferrer" className="underline underline-offset-2">{m[5]}</a> : <span key={key}>{m[5]}</span>);
+    } else out.push(<em key={key}>{m[7] ?? m[8]}</em>);
+    last = at + m[0].length;
+  }
+  if (last < source.length) out.push(source.slice(last));
+  return out;
+}
+
+const HEADING = /^(#{1,6})\s+(.*)$/;
+const BULLET = /^\s*[-*+]\s+(.*)$/;
+const ORDERED = /^\s*\d+[.)]\s+(.*)$/;
+const RULE = /^\s*([-*_])(\s*\1){2,}\s*$/;
+const TABLE_ROW = /^\s*\|.*\|\s*$/;
+const TABLE_SEP = /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+
+const cells = (line: string): string[] => line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+
+type Block =
+  | { kind: "heading"; level: number; text: string }
+  | { kind: "para"; text: string }
+  | { kind: "ul" | "ol"; items: string[] }
+  | { kind: "quote"; text: string }
+  | { kind: "code"; text: string }
+  | { kind: "rule" }
+  | { kind: "table"; head: string[]; rows: string[][] };
+
+/** Split markdown into blocks. Pure, so it is tested without rendering. */
+export function parseBlocks(markdown: string): Block[] {
+  const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
+  const blocks: Block[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim()) { i++; continue; }
+    if (/^\s*```/.test(line)) {
+      const body: string[] = [];
+      for (i++; i < lines.length && !/^\s*```/.test(lines[i]); i++) body.push(lines[i]);
+      i++;
+      blocks.push({ kind: "code", text: body.join("\n") });
+      continue;
+    }
+    const h = HEADING.exec(line);
+    if (h) { blocks.push({ kind: "heading", level: h[1].length, text: h[2].trim() }); i++; continue; }
+    if (RULE.test(line)) { blocks.push({ kind: "rule" }); i++; continue; }
+    if (TABLE_ROW.test(line) && i + 1 < lines.length && TABLE_SEP.test(lines[i + 1])) {
+      const rows: string[][] = [];
+      let j = i + 2;
+      for (; j < lines.length && TABLE_ROW.test(lines[j]); j++) rows.push(cells(lines[j]));
+      blocks.push({ kind: "table", head: cells(line), rows });
+      i = j;
+      continue;
+    }
+    if (BULLET.test(line) || ORDERED.test(line)) {
+      const ordered = ORDERED.test(line) && !BULLET.test(line);
+      const items: string[] = [];
+      for (; i < lines.length; i++) {
+        const m = (ordered ? ORDERED : BULLET).exec(lines[i]);
+        if (!m) break;
+        items.push(m[1]);
+      }
+      blocks.push({ kind: ordered ? "ol" : "ul", items });
+      continue;
+    }
+    if (/^\s*>/.test(line)) {
+      const body: string[] = [];
+      for (; i < lines.length && /^\s*>/.test(lines[i]); i++) body.push(lines[i].replace(/^\s*>\s?/, ""));
+      blocks.push({ kind: "quote", text: body.join(" ") });
+      continue;
+    }
+    const para: string[] = [];
+    for (; i < lines.length && lines[i].trim() && !HEADING.test(lines[i]) && !BULLET.test(lines[i]) && !ORDERED.test(lines[i]) && !/^\s*(```|>)/.test(lines[i]); i++) para.push(lines[i].trim());
+    blocks.push({ kind: "para", text: para.join(" ") });
+  }
+  return blocks;
+}
+
+const HEADING_CLASS = ["", "text-lg font-semibold", "text-base font-semibold", "text-sm font-semibold", "text-sm font-medium", "text-sm font-medium", "text-sm font-medium"];
+
+function BlockView({ block, k }: { block: Block; k: number }): ReactNode {
+  switch (block.kind) {
+    case "heading": {
+      const Tag = `h${Math.min(block.level + 1, 6)}` as "h2";
+      return <Tag className={cn("mt-4 text-foreground first:mt-0", HEADING_CLASS[block.level])}>{renderInline(block.text, `h${k}-`)}</Tag>;
+    }
+    case "ul":
+    case "ol": {
+      const Tag = block.kind;
+      return <Tag className={cn("my-2 space-y-1 pl-5", block.kind === "ul" ? "list-disc" : "list-decimal")}>{block.items.map((t, n) => <li key={n}>{renderInline(t, `l${k}-${n}-`)}</li>)}</Tag>;
+    }
+    case "quote": return <blockquote className="my-2 border-l-2 border-border pl-3 text-muted-foreground">{renderInline(block.text, `q${k}-`)}</blockquote>;
+    case "code": return <pre className="my-2 overflow-x-auto rounded-md bg-muted p-3 text-xs"><code>{block.text}</code></pre>;
+    case "rule": return <hr className="my-3 border-border" />;
+    case "table":
+      return (
+        <div className="my-2 overflow-x-auto">
+          <table className="w-full border-collapse text-left text-xs">
+            <thead><tr>{block.head.map((c, n) => <th key={n} className="border-b border-border px-2 py-1 font-medium">{renderInline(c, `th${k}-${n}-`)}</th>)}</tr></thead>
+            <tbody>{block.rows.map((r, ri) => <tr key={ri}>{r.map((c, n) => <td key={n} className="border-b border-border px-2 py-1 align-top">{renderInline(c, `td${k}-${ri}-${n}-`)}</td>)}</tr>)}</tbody>
+          </table>
+        </div>
+      );
+    default: return <p className="my-2 leading-6">{renderInline(block.text, `p${k}-`)}</p>;
+  }
+}
+
+export interface SafeMarkdownProps {
+  markdown: string;
+  className?: string;
+}
+
+export function SafeMarkdown({ markdown, className }: SafeMarkdownProps) {
+  return (
+    <div data-testid="safe-markdown" className={cn("text-sm text-foreground", className)}>
+      {parseBlocks(markdown).map((b, n) => <BlockView key={n} block={b} k={n} />)}
+    </div>
+  );
+}

package/blocks/company-intelligence/recipes/read-competitors-and-news.ts

@@ -0,0 +1,33 @@
+/**
+ * @title Read the competitors and the news the research found
+ * @when Feeding a briefing, a battle-card draft or a Slack digest. Both reads are free. They describe the competitors of YOUR
+ * website (the research is locked to it) and brand news about YOUR company, not about arbitrary companies, and the
+ * API has no lookup for another company's profile, technology or org chart. Article text and URLs come from the web: treat
+ * them as untrusted text and only open http(s) URLs.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Source = { data?: Record<string, unknown> | null; collected_at?: string };
+const entry = (res: unknown): Source => ((res as { data?: Source } | null)?.data ?? (res as Source) ?? {}) as Source;
+
+export interface Competitor { name?: string; domain?: string; description?: string; competitive_type?: string; similarity?: string; confidence?: string; reasoning?: string }
+export interface Article { title?: string; url?: string; description?: string; published_at?: string; sentiment?: number | null; source?: { name?: string } }
+
+export async function competitors(websiteUrl: string): Promise<Competitor[]> {
+  const res = entry(await g8.api.companyIntelligence.getIntelligenceData({ path: { data_type: "competitor_discovery" }, query: { website_url: websiteUrl } }));
+  return (Array.isArray(res.data?.competitors) ? res.data?.competitors : []) as Competitor[];
+}
+
+/** Only http(s) links, newest first. `sentiment` is -1 to 1 or null (unknown, not neutral). */
+export async function recentNews(websiteUrl: string): Promise<Article[]> {
+  const res = entry(await g8.api.companyIntelligence.getIntelligenceData({ path: { data_type: "brand_news" }, query: { website_url: websiteUrl } }));
+  const articles = (Array.isArray(res.data?.articles) ? res.data?.articles : []) as Article[];
+  return articles.filter((a) => /^https?:\/\//i.test(a.url ?? "")).sort((a, b) => String(b.published_at ?? "").localeCompare(String(a.published_at ?? "")));
+}
+
+/** Everything collected, keyed by source type, in one read. */
+export async function everything(websiteUrl: string) {
+  return entry(await g8.api.companyIntelligence.getAllIntelligenceData({ path: { website_url: websiteUrl } })) as Record<string, Source>;
+}

package/blocks/company-intelligence/recipes/research-your-website.ts

@@ -0,0 +1,43 @@
+/**
+ * @title Research your own website and read the company profile
+ * @when Setting up company intelligence for a workspace. The research is locked to ONE website (the workspace's primary
+ * website, set by the first run), so this reads it first and never guesses a domain. Starting a run is BILLABLE and the API
+ * quotes no price (it is metered by usage): tell a human what will be collected and get a yes first. A run finished less than an
+ * hour ago is returned as is (no new work, no charge) unless `force` is true. Order: primary website -> analyze -> poll the
+ * run -> read the company profile.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Body = Record<string, unknown>;
+const body = (res: unknown): Body => ((res as { data?: Body } | null)?.data ?? (res as Body) ?? {}) as Body;
+
+/** The website the research is locked to, or null before the first run. Never invent one. */
+export async function primaryWebsite(): Promise<string | null> {
+  const res = body(await g8.api.companyIntelligence.getIntelligencePrimaryWebsite());
+  return typeof res.primary_website_url === "string" && res.primary_website_url ? res.primary_website_url : null;
+}
+
+/** Billable. Only after a person approved researching `websiteUrl`. With no primary website yet, this one becomes the locked one. */
+export async function startResearch(websiteUrl: string, force = false) {
+  const res = body(await g8.api.companyIntelligence.analyzeWebsite({ body: force ? { website_url: websiteUrl, force: true } : { website_url: websiteUrl } }));
+  return res.task_id as string;
+}
+
+export async function waitForRun(taskId: string) {
+  let delay = 3000;
+  for (let i = 0; i < 100; i++) {
+    const run = body(await g8.api.companyIntelligence.getIntelligenceStatus({ path: { task_id: taskId } }));
+    if (run.status !== "pending" && run.status !== "running") return run;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(15000, Math.round(delay * 1.3));
+  }
+  throw new Error("the research did not finish in time; read the status again later");
+}
+
+/** Free. A source that was not collected answers 404: treat that as "not collected", not as an error. */
+export async function companyProfile(websiteUrl: string) {
+  const entry = body(await g8.api.companyIntelligence.getIntelligenceData({ path: { data_type: "company_enrichment" }, query: { website_url: websiteUrl } }));
+  return (entry.data ?? null) as Record<string, unknown> | null;
+}

package/blocks/company-intelligence/recipes/write-the-research-reports.ts

@@ -0,0 +1,54 @@
+/**
+ * @title Write the six research reports, follow them and approve one
+ * @when Building market research from your website. Writing a report is the most expensive single action in Studio and
+ * the API quotes no price: `generateResearchReport` is one long multi-pass run, `generateAllResearchReports` is six,
+ * `resumeResearchWorkflow` writes every report that is not finished. Read the workflow first to count them, tell a human the
+ * number, and get a yes. Approving a report indexes it into the knowledge base that campaigns and the copilot read.
+ * Order: workflow status -> generate (or retry a failed one) -> poll the workflow -> read the report -> approve.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Body = Record<string, unknown>;
+const body = (res: unknown): Body => ((res as { data?: Body } | null)?.data ?? (res as Body) ?? {}) as Body;
+
+export interface Slot { id: string | null; report_number: number; report_type: string; status: string; approved?: boolean }
+
+/** Free. Always six slots (`report_1`..`report_6`), including the ones not written yet. */
+export async function workflow(websiteUrl: string) {
+  const w = body(await g8.api.research.getResearchWorkflowStatus({ query: { website_url: websiteUrl } }));
+  const slots = Object.values((w.reports ?? {}) as Record<string, Slot>);
+  return { status: w.workflow_status as string, slots, missing: slots.filter((s) => s.status !== "completed" && s.status !== "approved" && s.status !== "generating") };
+}
+
+/** Billable. `reportNumber` is 1 to 6. */
+export async function writeReport(websiteUrl: string, reportNumber: number) {
+  return g8.api.research.generateResearchReport({ body: { website_url: websiteUrl, report_number: reportNumber } });
+}
+
+/** Billable. Re-runs ONE failed report; `reportType` is one of the six types in the workflow slots. */
+export async function retryFailed(websiteUrl: string, reportType: "review_sentiment" | "competitive_teardown" | "voice_of_customer" | "gtm_channel" | "analyst_media" | "buyer_psychology") {
+  return g8.api.research.retryResearchReport({ body: { website_url: websiteUrl, report_type: reportType } });
+}
+
+export async function waitForReports(websiteUrl: string) {
+  let delay = 5000;
+  for (let i = 0; i < 200; i++) {
+    const w = await workflow(websiteUrl);
+    if (!w.slots.some((s) => s.status === "generating")) return w;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(30000, Math.round(delay * 1.3));
+  }
+  throw new Error("the reports did not finish in time; read the workflow again later");
+}
+
+/** Free. The markdown is model output: render it as text, never as HTML. */
+export async function readReport(reportId: string) {
+  return body(await g8.api.research.getResearchReport({ path: { report_id: reportId } }));
+}
+
+/** Free, but it publishes the report to everything that reads the knowledge base. */
+export async function approve(reportId: string) {
+  return g8.api.research.approveResearchReport({ path: { report_id: reportId } });
+}

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

@@ -16,6 +16,7 @@
 import { useState } from "react";
 import { Button, Input, Skeleton } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
@@ -30,6 +31,8 @@ export interface CopilotMemoryProps {
   className?: string;
 }
 
+/** The memory API has no paging: a full read is announced under the list. */
+const MEMORY_LIMIT = 100;
 const idOf = (m: MemoryRow): string => m.memory_id ?? m.id ?? "";
 
 export function CopilotMemory({ scope = "user", className }: CopilotMemoryProps) {
@@ -37,7 +40,7 @@ export function CopilotMemory({ scope = "user", className }: CopilotMemoryProps)
   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 memories = useG8Query((signal) => g8Get("/copilot/memory", { scope, limit: MEMORY_LIMIT }, { 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(); } });
@@ -62,6 +65,7 @@ export function CopilotMemory({ scope = "user", className }: CopilotMemoryProps)
           </li>
         ))}
       </ul>
+      <FirstNotice shown={rows.length} limit={MEMORY_LIMIT} noun="memories" />
       {!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}
 
@@ -73,7 +77,7 @@ export function CopilotMemory({ scope = "user", className }: CopilotMemoryProps)
             {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}
+                {t.requires_approval || t.needs_approval ? <span className="text-xs text-warning-foreground">needs approval</span> : null}
               </li>
             ))}
           </ul>

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

@@ -153,7 +153,7 @@ export function CopilotPanel({ context, initialTab = "ask", confirmEveryMessage
               <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 {brand.linkLabel} before it runs: {t.needsApproval.join(", ")}</p> : null}
+                {t.needsApproval?.length ? <p className="mt-1 text-xs text-warning-foreground">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-team-chat.tsx

@@ -19,6 +19,7 @@
 import { useEffect, useRef, useState } from "react";
 import { Button, Input } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
@@ -43,6 +44,9 @@ interface Page { conversation_id?: string; messages?: WorkMessageRow[] }
 
 const newKey = (): string => `team-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 
+/** The agents roster read has no paging here: a full read is announced under the composer. */
+const AGENT_LIMIT = 50;
+
 export function CopilotTeamChat({ channelId, pollMs = 4000, hideChannelPicker, className }: CopilotTeamChatProps) {
   const [channel, setChannel] = useState<string | undefined>(channelId);
   const [text, setText] = useState("");
@@ -51,7 +55,7 @@ export function CopilotTeamChat({ channelId, pollMs = 4000, hideChannelPicker, c
   const draftKey = useRef(newKey());
 
   const channels = useG8Query((signal) => g8Get("/work/channels", undefined, { signal }), [], { enabled: !(hideChannelPicker && channelId) });
-  const agents = useG8Query((signal) => g8Get("/work/agents", { limit: 50 }, { signal }), []);
+  const agents = useG8Query((signal) => g8Get("/work/agents", { limit: AGENT_LIMIT }, { signal }), []);
   const rows = listOf<WorkChannel>(channels.data, "channels");
   const roster = listOf<AgentRow>(agents.data, "items");
   const active = channel ?? rows[0]?.id ?? undefined;
@@ -103,6 +107,7 @@ export function CopilotTeamChat({ channelId, pollMs = 4000, hideChannelPicker, c
               onKeyDown={(e) => { if (e.key === "Enter" && text.trim() && !post.loading) submit(); }} />
             <Button loading={post.loading} disabled={!text.trim()} onClick={submit}>Post</Button>
           </div>
+          <FirstNotice shown={roster.length} limit={AGENT_LIMIT} noun="agents" />
         </>
       ) : null}
 

package/blocks/crm/README.md

@@ -18,6 +18,23 @@ Three finished screens compose the parts below into complete workspaces. Each ne
 | `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` |
 
+### Record actions on contacts
+
+`ContactsScreen` also carries the write actions a CRM needs. Each exists three ways, a row (the "..." button), a selection (the bar
+above the table) and the open contact, and each is an exported component you can place yourself.
+
+| Action | Component | Notes |
+|---|---|---|
+| Assign or remove the owner of a WHOLE LIST | `OwnerAssignListButton` (via `ContactsScreen`'s `renderOwnerPicker`) | Never for a selection: the API assigns owners by filter (`list_id` + `filterModel`) across every match, and has no id-addressed owner write (API gap: `assign-owner` needs an `ids` field). The picker is injected (`renderOwnerPicker={(p) => <MemberPicker label="New owner" {...p} />}`) so crm stays free of the pickers block; without it the action is hidden. Offered only with a list in scope and no other filter; N is the list's real count; assign and remove are both confirmed with the list and N. |
+| Tags | `ContactTagChips` (open contact), `TagAssignButton` (selection), `TagManager` (create, rename, recolour, archive, delete, merge) | Delete states how many contacts lose the tag and can move them to another tag first. Merge removes the source tags. A tag's description cannot be cleared (the API ignores null), so it is not editable. |
+| Edit one field on a selection | `BulkUpdateButton` | Title, department, seniority, city, state, country. Chunks of 100, "N of M updated". Clearing is not offered (no documented clear). |
+| Verify email | `VerifyEmailButton` | Billable, about 1 credit per email. Only contacts with an unlocked email are counted and sent; the result line shows the credits actually charged. Max 1000. |
+| Unlock info | `UnlockInfoButton` | Billable, 1 credit per newly unlocked contact. Only locked contacts are counted and sent. Max 1000 per call. |
+| AI documents | `ContactDocumentsTab` | Write, rewrite, write all, read. Billable with no published price, so the confirm shows none. Rewrite replaces the stored text. |
+| Signals and next best step | `ContactInsightsTab` | Signals load on open. The next best step is a billable GET, so it is a button behind a confirm. |
+
+Prerequisites added: the `enrichment:run` scope (verify, unlock, documents, next best step). The owner action needs the `team-members` prefix and `team:read` only in apps that inject a picker (they already include `pickers`).
+
 ```tsx
 "use client";
 import { ContactsScreen } from "@/components/g8/crm/contacts-screen";
@@ -148,3 +165,11 @@ Ask the person: who may delete or merge records (decide it in the proxy's `autho
 | 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`) |
+
+## Cross-block glue
+
+- `ContactLookupLink` (`components/contact-lookup-link.tsx`): "Open contact" for something that only knows an email (an inbox thread, a meeting attendee). It looks the email up (`GET /contacts?email=`) and shows a button only when a contact has it; `onOpen(contactId)` routes to your contacts screen. `ContactsScreen.onOpenCompany`, `CompaniesScreen.onOpenContact` and `TasksScreen.onOpenRecord` are the other ends of the same links: the stack pages pass them (`router.push("/companies?id=...")`).
+- `ContactLookupLink` can also create: pass `createIfMissing` (optionally with the sender's `firstName`/`lastName`) and a stranger gets "Add to contacts" (`POST /contacts`, then it opens the new contact). Nothing is offered while the lookup loads or after it failed.
+- `RecordOpenLinks` (`components/record-open-links.tsx`): "Open contact" and "Open company" for something that only knows ids (a call log entry, a visitor). The ids are verified with `GET /contacts/{id}` and `GET /companies/{id}` first (optionally against an expected company domain or contact name), so a link never points at a missing or wrong record.
+
+- `RecordEngagementTab` (`components/record-engagement-tab.tsx`): engagement counts, last touch (contacts) and pages visited for a contact or company, an `extraDetailTabs` entry: `{ id: "engagement", label: "Engagement", render: (c) => <RecordEngagementTab kind="contacts" id={c.id} /> }`. Reads `getContactEngagementSummary` / `getCompanyEngagementSummary` and `getContactSitesVisited` / `getCompanySitesVisited`. Also: the contact subtitle is `contactSubtitle(contact)` ("VP of Sales at Acme"; the company is never the person's own name, and "at" is left out without a company).