@graph8/sdk 0.370.0 → 0.373.0

package/blocks/company-intelligence/components/wiki-document-detail.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+/**
+ * WikiDocumentDetail: the complete screen for one wiki document. Finds it by id (so `?id=` deep links work), shows its
+ * content as safe formatted text (markdown from the API is never turned into HTML), its state and version, and can write
+ * it again from the collected research.
+ *
+ * SDK operations, in order:
+ *   1. getGlobalContextTreeFlat           GET  /global-context/tree/flat            (read)
+ *   2. getIntelligencePrimaryWebsite      GET  /intelligence/primary-website        (read, through useResearchTarget)
+ *   3. generateGlobalContextDocument      POST /global-context/generate/{doc_type}  (BILLABLE) a model rewrites this ONE document; ConfirmSpendDialog first
+ * After the call is accepted the document is read again until its update time moves. The confirm shows what this document
+ * used the last time it was written (a real number from the document), when the API reports one; there is no advance price.
+ */
+import { useRef, useState, type ReactNode } from "react";
+import { RefreshCw } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList, EmptyValue } from "@/g8/components/screen/key-value-list";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Post } from "@/g8/lib/g8-client";
+import { refreshIntelligence, useResearchTarget, useWikiDocuments } from "../hooks/use-intelligence";
+import { docTitle, humanize, num, text, when } from "../lib/intelligence-types";
+import { SafeMarkdown } from "../lib/safe-markdown";
+
+export interface WikiDocumentDetailProps {
+  docId: string;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  onChanged?: () => void;
+  extraActions?: ReactNode;
+  extraTabs?: { id: string; label: string; content: ReactNode }[];
+}
+
+export function WikiDocumentDetail({ docId, onClose, onExpand, onCollapse, onChanged, extraActions, extraTabs }: WikiDocumentDetailProps) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const target = useResearchTarget();
+  const { docs, error, refetch } = useWikiDocuments();
+  const [waiting, setWaiting] = useState(false);
+  const before = useRef<string | null>(null);
+  const doc = docs?.find((d) => d.id === docId);
+
+  useJobPoll<string | null>(async () => { const rows = await refetch(); return text(rows?.find((d) => d.id === docId)?.updated_at); }, {
+    enabled: waiting, intervalMs: 4000, maxAttempts: 40,
+    isTerminal: (updated) => updated != null && updated !== before.current,
+    onDone: () => { setWaiting(false); void refreshIntelligence(); onChanged?.(); },
+  });
+
+  if (error) return <ApiError error={error} title="Could not load the document" onRetry={() => void refetch()} />;
+  if (!docs) return <Skeleton className="h-40 w-full" />;
+  if (!doc) return <EmptyState title="Document not found" description="It may have been deleted." />;
+
+  const title = docTitle(doc);
+  const lastCredits = num(doc.credits_used);
+  const canRegenerate = Boolean(doc.file_type && target.primary);
+  const askRegenerate = () => ask({
+    tier: "billable",
+    title: `Rewrite ${title}`,
+    confirmLabel: "Rewrite",
+    estimatedCredits: lastCredits != null && lastCredits > 0 ? lastCredits : undefined,
+    description: <p>A model writes this one document again from the collected research and replaces version {doc.version ?? "the current one"}.{lastCredits != null && lastCredits > 0 ? " The credits shown are what it used the last time." : " The API gives no price in advance."}</p>,
+    run: async () => {
+      before.current = text(doc.updated_at);
+      await g8Post(`/global-context/generate/${encodeURIComponent(doc.file_type as string)}`, { doc_type: doc.file_type, website_url: target.primary });
+      setWaiting(true);
+    },
+    onDone: () => { void refreshIntelligence(); },
+  });
+  const actions = (
+    <div className="flex flex-wrap items-center gap-2">
+      <Button type="button" size="sm" variant="outline" disabled={!canRegenerate || waiting} onClick={askRegenerate} title={canRegenerate ? undefined : "Start the website research first"}>
+        <RefreshCw className="size-3.5" aria-hidden />{waiting ? "Writing..." : "Rewrite"}
+      </Button>
+      {extraActions}
+    </div>
+  );
+  const content = text(doc.content);
+  const tabs = [
+    { id: "document", label: "Document", content: content ? <SafeMarkdown markdown={content} /> : <EmptyState title="No content yet" description="This document has not been written." compact /> },
+    {
+      id: "details", label: "Details",
+      content: (
+        <KeyValueList columns={2} items={[
+          { label: "Type", value: text(doc.file_type) ?? <EmptyValue />, mono: true },
+          { label: "Folder", value: text(doc.folder_path) ?? <EmptyValue /> },
+          { label: "Category", value: text(doc.category) ?? <EmptyValue /> },
+          { label: "Version", value: doc.version ?? <EmptyValue /> },
+          { label: "Last updated", value: when(doc.updated_at) ?? <EmptyValue /> },
+          { label: "Credits used last time", value: lastCredits != null && lastCredits > 0 ? lastCredits : <EmptyValue /> },
+        ]} />
+      ),
+    },
+  ];
+  return (
+    <>
+      <DetailPanel
+        title={title}
+        subtitle={text(doc.folder_path) ?? undefined}
+        badges={<StatusPill tone={toneForStatus(doc.status ?? "")}>{doc.status ? humanize(doc.status) : "Unknown"}</StatusPill>}
+        actions={actions}
+        tabs={extraTabs?.length ? [...tabs, ...extraTabs] : tabs}
+        onClose={onClose}
+        onExpand={onExpand}
+        onCollapse={onCollapse}
+      />
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </>
+  );
+}

package/blocks/company-intelligence/components/wiki-documents.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+/**
+ * WikiDocuments: the wiki documents graph8 writes from the research (brand, audience, market, messaging ...), listed by
+ * folder with their state, version and last update. Search and a folder filter narrow the list. Click a row to open it.
+ *
+ * SDK operations, in order:
+ *   1. getGlobalContextTreeFlat  GET /global-context/tree/flat  (read)  every wiki document, content included
+ * The API does not page this list (a few dozen documents); the header says how many there are. Folder and search filter on
+ * screen. Opening and regenerating a document is WikiDocumentDetail.
+ */
+import { useMemo, useState } from "react";
+import { FileText } from "lucide-react";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { RecordLink } from "@/g8/components/screen/record-link";
+import { SelectFilter } from "@/g8/components/screen/filter-controls";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { plural } from "@/g8/lib/plural";
+import { useWikiDocuments } from "../hooks/use-intelligence";
+import { docTitle, humanize, text, whenDate } from "../lib/intelligence-types";
+import type { WikiDoc } from "../lib/intelligence-types";
+
+export interface WikiDocumentsProps {
+  onSelect?: (doc: WikiDoc) => void;
+  selectedId?: string;
+  /** The URL param the owning screen reads for the open document, so Cmd-click opens it in a new tab. */
+  idParam?: string;
+  className?: string;
+}
+
+export function WikiDocuments({ onSelect, selectedId, idParam, className }: WikiDocumentsProps) {
+  const { docs, error, refetch } = useWikiDocuments();
+  const [search, setSearch] = useState("");
+  const [folder, setFolder] = useState("");
+  const folders = useMemo(() => [...new Set((docs ?? []).map((d) => text(d.folder_path)).filter(Boolean) as string[])].sort(), [docs]);
+  if (error) return <ApiError error={error} title="Could not load the documents" onRetry={() => void refetch()} />;
+  if (!docs) return <Skeleton className="h-40 w-full" />;
+  if (docs.length === 0) return <EmptyState title="No documents yet" description="The wiki documents are written from the research. Run the website research first." icon={<FileText />} />;
+  const needle = search.trim().toLowerCase();
+  const rows = docs.filter((d) => (!folder || d.folder_path === folder) && (!needle || docTitle(d).toLowerCase().includes(needle)));
+  return (
+    <div className={className}>
+      <Toolbar
+        search={{ value: search, onChange: setSearch, placeholder: "Search documents", label: "Search documents" }}
+        filters={folders.length > 1 ? <SelectFilter label="folder" value={folder} onChange={setFolder} any="All folders" options={folders} /> : undefined}
+        status={rows.length === docs.length ? `All ${plural(docs.length, "document")}` : `${rows.length.toLocaleString()} of ${plural(docs.length, "document")}`}
+      />
+      {rows.length === 0 ? <EmptyState title="No documents match" description="Try another search or folder." compact /> : (
+        <ul className="mt-2 divide-y divide-border rounded-md border border-border">
+          {rows.map((d) => (
+            <li key={d.id} aria-current={d.id === selectedId ? "true" : undefined} className="flex items-center justify-between gap-3 px-3 py-2 text-sm aria-[current=true]:bg-muted">
+              <div className="min-w-0">
+                <RecordLink id={d.id} param={idParam} onOpen={() => onSelect?.(d)}>{docTitle(d)}</RecordLink>
+                <div className="text-xs text-muted-foreground">{[text(d.folder_path), d.version != null ? `Version ${d.version}` : null, whenDate(d.updated_at) ? `Updated ${whenDate(d.updated_at)}` : null].filter(Boolean).join(", ")}</div>
+              </div>
+              <StatusPill tone={toneForStatus(d.status ?? "")} quiet>{d.status ? humanize(d.status) : "Unknown"}</StatusPill>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/blocks/company-intelligence/hooks/use-intelligence.ts

@@ -0,0 +1,173 @@
+"use client";
+
+/**
+ * Shared reads for the company-intelligence components, all cached under the `company-intelligence` key prefix so one
+ * `refreshIntelligence()` after any write refreshes every panel that shows the result.
+ *
+ * SDK operations, in order:
+ *   1. getIntelligencePrimaryWebsite  GET /intelligence/primary-website   (read)  the website the research is locked to
+ *   2. getIntelligenceOrgDomain       GET /intelligence/org-domain        (read)  a suggestion for it, read only while none is set
+ *   3. getLatestIntelligenceTask      GET /intelligence/latest-task       (read)  the most recent research run
+ *   4. getAllIntelligenceData         GET /intelligence/all/{website_url} (read)  every source collected for one website
+ *   5. getIntelligenceStatus          GET /intelligence/status/{task_id}  (read)  the step states of one run
+ *   6. listIntelligenceDocuments      GET /intelligence/documents         (read)  every collected source
+ *   7. getGlobalContextTreeFlat       GET /global-context/tree/flat       (read)  the wiki documents
+ *   8. getGlobalContextTree           GET /global-context/tree            (read)  how many wiki documents exist and are finished
+ *   9. getResearchWorkflowStatus      GET /research-reports/workflow      (read)  the six research reports and how far they are
+ *  10. getIntelligenceData            GET /intelligence/data/{data_type}  (read)  one collected source
+ */
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { invalidate } from "@/g8/lib/g8-cache";
+import { g8Get } from "@/g8/lib/g8-client";
+import { canonicalDomain, intelBody, isRec, num, rowsOf, text } from "../lib/intelligence-types";
+import type { IntelDocument, LatestTask, Rec, RunStatus, WikiDoc, WorkflowStatus } from "../lib/intelligence-types";
+
+export const INTEL_KEY = "company-intelligence";
+
+/** Mark every intelligence read stale after a write, so the panels on screen show the new state. */
+export function refreshIntelligence(): Promise<void> {
+  return invalidate([INTEL_KEY]);
+}
+
+/**
+ * The website intelligence is about. `primary` is the workspace's own website (set by the first research run, then
+ * locked); `suggested` is the company domain in the workspace settings, offered only while no primary website exists.
+ * Neither is ever invented: with both null the person types the website.
+ */
+export function useResearchTarget() {
+  const primary = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get("/intelligence/primary-website", undefined, { signal }));
+      return isRec(body) ? text(body.primary_website_url) : null;
+    },
+    [],
+    { key: [INTEL_KEY, "primary-website"] },
+  );
+  const wantSuggestion = primary.data === null;
+  const suggestion = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get("/intelligence/org-domain", undefined, { signal }));
+      return isRec(body) ? text(body.company_domain) : null;
+    },
+    [],
+    { key: [INTEL_KEY, "org-domain"], enabled: wantSuggestion },
+  );
+  return {
+    primary: primary.data ?? null,
+    primaryDomain: primary.data ? canonicalDomain(primary.data) : null,
+    suggested: wantSuggestion ? suggestion.data ?? null : null,
+    loading: primary.loading && primary.data === undefined,
+    error: primary.error,
+    refetch: primary.refetch,
+  };
+}
+
+/** The most recent research run of the workspace, or null when none ran yet. */
+export function useLatestRun() {
+  const q = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get("/intelligence/latest-task", undefined, { signal }));
+      return isRec(body) && text(body.task_id) ? (body as LatestTask) : null;
+    },
+    [],
+    { key: [INTEL_KEY, "latest-run"] },
+  );
+  return { run: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/**
+ * Everything collected for one website, keyed by source type (`GET /intelligence/all/{website_url}`, read).
+ * `host` is the website as a host (no scheme); pass null to hold the request.
+ */
+export function useAllIntelligence(host: string | null) {
+  const q = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get(`/intelligence/all/${encodeURIComponent(host as string)}`, undefined, { signal }));
+      const out: Record<string, Rec> = {};
+      if (isRec(body)) for (const [type, entry] of Object.entries(body)) if (isRec(entry)) out[type] = entry;
+      return out;
+    },
+    [host],
+    { key: [INTEL_KEY, "all", host ?? "none"], enabled: Boolean(host) },
+  );
+  return { entries: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/** The `data` blob of one source entry, or null. */
+export function entryData(entry: Rec | undefined | null): Rec | null {
+  return entry && isRec(entry.data) ? entry.data : null;
+}
+
+/** One read of a run's step states (`GET /intelligence/status/{task_id}`, read). For the live view use ResearchRun, which polls. */
+export function useRunStatus(taskId: string | null | undefined) {
+  const q = useG8Query(
+    async (signal) => intelBody<RunStatus>(await g8Get(`/intelligence/status/${encodeURIComponent(taskId as string)}`, undefined, { signal })),
+    [taskId],
+    { key: [INTEL_KEY, "status", taskId ?? "none"], enabled: Boolean(taskId) },
+  );
+  return { status: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/** Every collected source of the workspace (`GET /intelligence/documents`, read), newest first as the API returns them. */
+export function useSourceDocuments() {
+  const q = useG8Query(
+    async (signal) => rowsOf<IntelDocument>(intelBody(await g8Get("/intelligence/documents", undefined, { signal })), "documents"),
+    [],
+    { key: [INTEL_KEY, "documents"] },
+  );
+  return { docs: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/**
+ * The wiki documents graph8 writes from the research (brand, audience, market, messaging ...), content included
+ * (`GET /global-context/tree/flat`, read). The API does not page this list and it holds a few dozen documents.
+ */
+export function useWikiDocuments() {
+  const q = useG8Query(
+    async (signal) => rowsOf<WikiDoc>(intelBody(await g8Get("/global-context/tree/flat", undefined, { signal })), "documents"),
+    [],
+    { key: [INTEL_KEY, "wiki", "flat"] },
+  );
+  return { docs: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/** How many wiki documents exist and how many are finished (`GET /global-context/tree`, read). Null when the API did not say. */
+export function useWikiStats() {
+  const q = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get("/global-context/tree", undefined, { signal }));
+      const stats = isRec(body) && isRec(body.stats) ? body.stats : null;
+      const total = num(stats?.total);
+      const completed = num(stats?.completed);
+      return total != null && completed != null ? { total, completed } : null;
+    },
+    [],
+    { key: [INTEL_KEY, "wiki", "tree"] },
+  );
+  return { stats: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/**
+ * How the six-report research workflow is going for a website (`GET /research-reports/workflow`, read). It always lists
+ * all six slots, including the ones not generated yet. `host` null holds the request.
+ */
+export function useWorkflow(host: string | null) {
+  const q = useG8Query(
+    async (signal) => intelBody<WorkflowStatus>(await g8Get("/research-reports/workflow", { website_url: host }, { signal })),
+    [host],
+    { key: [INTEL_KEY, "workflow", host ?? "none"], enabled: Boolean(host) },
+  );
+  return { workflow: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/**
+ * One collected source for a website (`GET /intelligence/data/{data_type}`, read): the entry with its `data` blob,
+ * collection time and any edits. A 404 means the source was not collected (the query errors with status 404).
+ */
+export function useSourceEntry(dataType: string, host: string | null, enabled = true) {
+  return useG8Query(
+    async (signal) => intelBody<Rec>(await g8Get(`/intelligence/data/${encodeURIComponent(dataType)}`, host ? { website_url: host } : undefined, { signal })),
+    [dataType, host],
+    { key: [INTEL_KEY, "source", dataType, host ?? "any"], enabled },
+  );
+}

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);