@graph8/sdk 0.370.0 → 0.374.0

package/blocks/sequencer/components/sequence-stats.tsx

@@ -50,9 +50,9 @@ const STATES = ["", "waiting", "paused", "completed", "replied", "bounced", "ski
 
 function Tile({ label, value }: { label: string; value: string | number }) {
   return (
-    <div className="rounded border border-gray-200 p-3">
-      <div className="text-xs capitalize text-gray-500">{label}</div>
-      <div className="text-xl font-semibold">{value}</div>
+    <div className="rounded border border-border p-3">
+      <div className="text-xs capitalize text-muted-foreground">{label}</div>
+      <div className="text-xl font-medium">{value}</div>
     </div>
   );
 }
@@ -145,7 +145,7 @@ export function SequenceStats({ sequenceId, pageSize = 25, refreshSeconds, class
                 <TableCell>{st.step_order}</TableCell>
                 <TableCell>{st.step_type}</TableCell>
                 <TableCell>{st.total_contacts ?? 0}</TableCell>
-                <TableCell className="text-xs text-gray-600">
+                <TableCell className="text-xs text-muted-foreground">
                   {Object.entries(st.counts ?? {})
                     .filter(([, n]) => n > 0)
                     .map(([k, n]) => `${k}: ${n}`)
@@ -156,11 +156,11 @@ export function SequenceStats({ sequenceId, pageSize = 25, refreshSeconds, class
           </TableBody>
         </Table>
       ) : (
-        <p className="text-sm text-gray-500">No step activity yet.</p>
+        <p className="text-sm text-muted-foreground">No step activity yet.</p>
       )}
 
       {skips.length > 0 ? (
-        <p className="text-sm text-gray-600" data-testid="skip-reasons">
+        <p className="text-sm text-muted-foreground" data-testid="skip-reasons">
           Skipped contacts, counted once each: {skips.map(([k, n]) => `${k.replace(/^skipped_/, "").replace(/_/g, " ")} ${n}`).join(", ")}
         </p>
       ) : null}
@@ -171,7 +171,7 @@ export function SequenceStats({ sequenceId, pageSize = 25, refreshSeconds, class
             Contacts in
             <select
               aria-label="Contact state"
-              className="ml-2 h-8 rounded border border-gray-300 px-1"
+              className="ml-2 h-8 rounded border border-input px-1"
               value={state}
               onChange={(e) => {
                 setState(e.target.value);
@@ -201,7 +201,7 @@ export function SequenceStats({ sequenceId, pageSize = 25, refreshSeconds, class
             <TableBody>
               {rows.length === 0 ? (
                 <TableRow>
-                  <TableCell colSpan={4} className="text-sm text-gray-500">
+                  <TableCell colSpan={4} className="text-sm text-muted-foreground">
                     {contacts.loading ? "Loading..." : "No contacts in this state."}
                   </TableCell>
                 </TableRow>

package/blocks/sequencer/components/sequence-templates.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+/**
+ * SequenceTemplates: reusable sequence skeletons (a named list of steps). List, create, edit, archive, restore and USE
+ * them: "Use template" hands the template's steps to `onUse`, which SequencesScreen opens in the builder so you only add
+ * the audience list and the senders.
+ *
+ * SDK operations, in order:
+ *   1. GET   /sequencer/templates/sequences                (sequences.listSequenceTemplates)    read   (archived ones included; filtered here)
+ *   2. POST  /sequencer/templates/sequences                (sequences.createSequenceTemplate)   write
+ *   3. PATCH /sequencer/templates/sequences/{id}           (sequences.updateSequenceTemplate)   write  - ONLY the changed fields; the steps
+ *                                                           are sent (as the whole list, which replaces the old one) only when they changed
+ *   4. PATCH /sequencer/templates/sequences/{id}/archive   (sequences.archiveSequenceTemplate)  DESTRUCTIVE to archive -> ConfirmSpendDialog; restoring is a plain write
+ * A template is a COPY: using it, or changing it later, never touches a sequence built from it. The form is seeded from a
+ * LOADED template and Save stays disabled until something changed. A template can also be made from a finished sequence
+ * ("Save as template" in SequenceManageActions).
+ */
+import { useState } from "react";
+import { Archive, ArchiveRestore, FilePlus2, Pencil, Plus } from "lucide-react";
+import { Button, Input, Skeleton, 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 { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { sequenceTemplates, templateBodyFromSteps, templateToDraftSteps } from "../lib/sequencer-manage";
+import type { SequenceTemplate } from "../lib/sequencer-manage";
+import { KIND_LABEL, KINDS, newStep, stepIssues, toApiStep } from "../lib/sequencer-utils";
+import type { DraftStep, StepKind } from "../lib/sequencer-utils";
+import { StepEditor } from "./step-editor";
+
+export interface SequenceTemplatesProps {
+  /** Called when the person chooses "Use template": the template's name and an unsaved copy of its steps. */
+  onUse?: (template: { id: string; name: string; description: string; steps: DraftStep[] }) => void;
+  className?: string;
+}
+
+const stepsKey = (steps: DraftStep[]) => JSON.stringify(steps.map((s, i) => toApiStep(s, i + 1)));
+
+function TemplateForm({ loaded, onDone }: { loaded: SequenceTemplate | null; onDone: (changed: boolean) => void }) {
+  const [name, setName] = useState(loaded?.name ?? "");
+  const [description, setDescription] = useState(loaded?.description ?? "");
+  const [steps, setSteps] = useState<DraftStep[]>(() => (loaded ? templateToDraftSteps(loaded) : []));
+  const stepsChanged = loaded ? stepsKey(steps) !== stepsKey(templateToDraftSteps(loaded)) : steps.length > 0;
+  const save = useG8Mutation(async () => {
+    // A loaded step keeps its own name (same position and same step type); only new or retyped steps get the automatic one.
+    const api = steps.map((s, i) => {
+      const was = loaded?.steps[i];
+      const a = toApiStep(s, i + 1);
+      return { ...a, id: undefined, name: was && was.step_type === a.step_type ? was.name : undefined };
+    });
+    const body = templateBodyFromSteps(name, description, api);
+    if (!loaded) {
+      await g8Post("/sequencer/templates/sequences", body);
+      return;
+    }
+    const changes: Record<string, unknown> = {};
+    if (name.trim() !== loaded.name) changes.name = name.trim();
+    if (description.trim() !== loaded.description) changes.description = description.trim();
+    if (stepsChanged) changes.steps = body.steps;
+    await g8Patch(`/sequencer/templates/sequences/${encodeURIComponent(loaded.id)}`, changes);
+  }, { invalidates: ["sequences"] });
+  const dirty = loaded ? name.trim() !== loaded.name || description.trim() !== loaded.description || stepsChanged : true;
+  const valid = name.trim().length > 0 && dirty && steps.every((s) => stepIssues(s).length === 0);
+  const submit = async () => {
+    try {
+      await save.mutateAsync(undefined);
+      onDone(true);
+    } catch {
+      /* shown below */
+    }
+  };
+  const add = (kind: StepKind) => setSteps((all) => [...all, newStep(kind)]);
+  return (
+    <form className="space-y-3 rounded-md border border-border p-3" aria-label={loaded ? `Edit ${loaded.name}` : "New sequence template"} onSubmit={(e) => { e.preventDefault(); if (valid) void submit(); }}>
+      <Input aria-label="Template name" placeholder="Template name" value={name} onChange={(e) => setName(e.target.value)} />
+      <Textarea aria-label="Description" rows={2} placeholder="What this sequence is for (optional)" value={description} onChange={(e) => setDescription(e.target.value)} />
+      {steps.map((s, i) => (
+        <StepEditor key={s.key} step={s} index={i + 1} onChange={(next) => setSteps((all) => all.map((x) => (x.key === s.key ? next : x)))} onRemove={() => setSteps((all) => all.filter((x) => x.key !== s.key))} />
+      ))}
+      <div className="flex flex-wrap gap-2">
+        {KINDS.map((k) => <Button key={k} type="button" size="sm" variant="outline" onClick={() => add(k)}>Add {KIND_LABEL[k].toLowerCase()} step</Button>)}
+      </div>
+      {save.error ? <ApiError error={save.error} title="Could not save the template" /> : null}
+      <div className="flex justify-end gap-2">
+        <Button type="button" variant="outline" size="sm" onClick={() => onDone(false)}>Cancel</Button>
+        <Button type="submit" size="sm" disabled={!valid || save.loading}>{loaded ? "Save changes" : "Create template"}</Button>
+      </div>
+    </form>
+  );
+}
+
+export function SequenceTemplates({ onUse, className }: SequenceTemplatesProps) {
+  const [editing, setEditing] = useState<SequenceTemplate | "new" | null>(null);
+  const [archiving, setArchiving] = useState<SequenceTemplate | null>(null);
+  const [showArchived, setShowArchived] = useState(false);
+  const [restoringId, setRestoringId] = useState<string | null>(null);
+  const list = useG8Query(async (signal) => sequenceTemplates(await g8Get("/sequencer/templates/sequences", undefined, { signal })), [], { key: ["sequences", "templates"] });
+  const archive = useG8Mutation(async (v: { template: SequenceTemplate; archived: boolean }) => {
+    await g8Patch(`/sequencer/templates/sequences/${encodeURIComponent(v.template.id)}/archive`, { is_archived: v.archived });
+    setArchiving(null);
+  }, { invalidates: ["sequences"], onError: () => setArchiving(null) });
+
+  if (list.error) return <ApiError error={list.error} title="Could not load the sequence templates" onRetry={() => void list.refetch()} className={className} />;
+  if (list.loading && !list.data) return <div aria-busy="true" className={`space-y-2 ${className ?? ""}`}><Skeleton className="h-12 w-full" /><Skeleton className="h-12 w-full" /></div>;
+  const rows = (list.data ?? []).filter((t) => showArchived || !t.archived);
+  const done = (changed: boolean) => { setEditing(null); if (changed) void list.refetch(); };
+
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <h3 className="font-medium">Sequence templates</h3>
+        <div className="flex items-center gap-2">
+          <label className="flex items-center gap-1 text-xs"><input type="checkbox" checked={showArchived} onChange={(e) => setShowArchived(e.target.checked)} />Show archived</label>
+          <Button size="sm" disabled={editing != null} onClick={() => setEditing("new")}><Plus className="mr-1 size-4" aria-hidden />New template</Button>
+        </div>
+      </div>
+      {editing === "new" ? <TemplateForm loaded={null} onDone={done} /> : null}
+      {rows.length === 0 && editing !== "new" ? (
+        <EmptyState compact title="No sequence templates yet" description="Save the steps of a sequence that works, then start new ones from it." action={<Button size="sm" onClick={() => setEditing("new")}>Create a template</Button>} />
+      ) : (
+        <ul aria-label="Sequence templates" className="divide-y rounded-md border border-border">
+          {rows.map((t) => (
+            <li key={t.id} className="p-2 text-sm">
+              {editing !== "new" && editing?.id === t.id ? (
+                <TemplateForm loaded={t} onDone={done} />
+              ) : (
+                <div className="flex items-center gap-2">
+                  <span className="min-w-0 flex-1"><span className="font-medium">{t.name}</span><span className="block truncate text-xs text-muted-foreground">{t.steps.length} {t.steps.length === 1 ? "step" : "steps"}{t.description ? ` - ${t.description}` : ""}</span></span>
+                  {t.archived ? <StatusPill tone="warning">archived</StatusPill> : null}
+                  {!t.archived && onUse ? <Button size="sm" variant="outline" onClick={() => onUse({ id: t.id, name: t.name, description: t.description, steps: templateToDraftSteps(t) })}><FilePlus2 className="mr-1 size-4" aria-hidden />Use template</Button> : null}
+                  <Button size="sm" variant="ghost" aria-label={`Edit ${t.name}`} disabled={editing != null} onClick={() => setEditing(t)}><Pencil className="size-4" aria-hidden /></Button>
+                  {t.archived ? (
+                    <Button size="sm" variant="ghost" aria-label={`Restore ${t.name}`} loading={archive.loading && restoringId === t.id} onClick={() => { setRestoringId(t.id); void archive.mutate({ template: t, archived: false }); }}><ArchiveRestore className="size-4" aria-hidden /></Button>
+                  ) : (
+                    <Button size="sm" variant="ghost" aria-label={`Archive ${t.name}`} onClick={() => setArchiving(t)}><Archive className="size-4" aria-hidden /></Button>
+                  )}
+                </div>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+      {archive.error ? <ApiError error={archive.error} title="Could not update the template" /> : null}
+      <ConfirmSpendDialog
+        open={archiving != null}
+        tier="destructive"
+        title={`Archive "${archiving?.name ?? ""}"?`}
+        description="It leaves the template list. Sequences already built from it are not changed. You can restore it from Show archived."
+        confirmLabel="Archive template"
+        affected={1}
+        confirming={archive.loading}
+        onConfirm={() => archiving && void archive.mutate({ template: archiving, archived: true })}
+        onCancel={() => setArchiving(null)}
+      />
+    </div>
+  );
+}

package/blocks/sequencer/components/sequences-screen.tsx

@@ -19,6 +19,10 @@
  *   - Open a sequence (deep link `?id=`): Results (stats, contacts, pause/resume one), Steps (edit copy), and
  *     "Enroll contacts": pick a list, tick contacts, confirm the recipient count.
  *
+ *   - "Templates" (header): sequence templates (list, create, edit, archive, use) and step templates (the same, plus AI drafts);
+ *     "Use template" opens the new-sequence sheet with the template's name and steps filled in. In an open sequence: Edit (rename and
+ *     settings), Sync audience, Save as template, Delete, a Senders tab, and removing a contact from the sequence.
+ *
  * SDK operations of its own (both read):
  *   1. listSequences  GET /sequences?limit=100  (counts for the stat strip)
  *   2. getSequence    GET /sequences/{id}       (header of the open sequence; also gives associated_list_id)
@@ -27,8 +31,8 @@
 
 import { useState } from "react";
 import type { ReactNode } from "react";
-import { ListOrdered, Plus } from "lucide-react";
-import { Button } from "@graph8/sdk/ui";
+import { LayoutTemplate, ListOrdered, Plus } from "lucide-react";
+import { Button, Tabs, TabsContent, TabsList, TabsTrigger } from "@graph8/sdk/ui";
 import { FormSheet } from "@/g8/components/screen/form-sheet";
 import { ScreenLayout } from "@/g8/components/screen/screen-layout";
 import { SplitView } from "@/g8/components/screen/split-view";
@@ -38,10 +42,12 @@ import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { useUrlState } from "@/g8/hooks/use-url-state";
 import { g8Get } from "@/g8/lib/g8-client";
 import { listOf, statusGroup } from "../lib/sequencer-utils";
-import type { SequenceRow } from "../lib/sequencer-utils";
+import type { DraftStep, SequenceRow } from "../lib/sequencer-utils";
 import { SequenceBuilder } from "./sequence-builder";
 import { SequenceDetail } from "./sequence-detail";
 import { SequenceList } from "./sequence-list";
+import { SequenceTemplates } from "./sequence-templates";
+import { StepTemplates } from "./step-templates";
 
 export interface SequencesScreenProps {
   /** Owner email sent with a new sequence (`user_email`). */
@@ -52,6 +58,8 @@ export interface SequencesScreenProps {
   renderDetailActions?: (sequence: SequenceRow) => ReactNode;
   /** Extra tabs in the open sequence's panel. */
   extraDetailTabs?: { id: string; label: string; render: (sequence: SequenceRow) => ReactNode }[];
+  /** Open an enrolled person in your contacts screen; without it the Contacts tab has no such button. */
+  onOpenContact?: (contactId: number) => void;
   className?: string;
 }
 
@@ -85,6 +93,8 @@ export function SequencesScreen(props: SequencesScreenProps) {
   const [contactId, setContactId] = useUrlState("enrollment", "");
   const [status, setStatus] = useUrlState("status", "");
   const [creating, setCreating] = useState(false);
+  const [templatesOpen, setTemplatesOpen] = useState(false);
+  const [prefill, setPrefill] = useState<{ name: string; steps: DraftStep[] } | null>(null);
   const [version, setVersion] = useState(0);
   const [listKey, setListKey] = useState(0);
   const summary = useG8Query((signal) => g8Get("/sequences", { limit: SUMMARY_LIMIT }, { signal }), [version], { key: ["sequences", "summary"] });
@@ -101,9 +111,14 @@ export function SequencesScreen(props: SequencesScreenProps) {
       description="Multi-channel outreach that runs on its own: build steps, enroll contacts, watch replies."
       icon={<ListOrdered className="h-5 w-5" aria-hidden />}
       actions={
-        <Button onClick={() => setCreating(true)}>
-          <Plus className="mr-1 h-4 w-4" aria-hidden /> New sequence
-        </Button>
+        <>
+          <Button variant="outline" onClick={() => setTemplatesOpen(true)}>
+            <LayoutTemplate className="mr-1 h-4 w-4" aria-hidden /> Templates
+          </Button>
+          <Button onClick={() => { setPrefill(null); setCreating(true); }}>
+            <Plus className="mr-1 h-4 w-4" aria-hidden /> New sequence
+          </Button>
+        </>
       }
       stats={stats}
     >
@@ -135,6 +150,7 @@ export function SequencesScreen(props: SequencesScreenProps) {
                 onStepChange={(v) => setStepId(v)}
                 contactId={contactId || undefined}
                 onContactChange={(v) => setContactId(v)}
+                onOpenContact={props.onOpenContact}
                 onClose={close}
                 onChanged={refreshList}
                 refreshKey={version}
@@ -146,9 +162,26 @@ export function SequencesScreen(props: SequencesScreenProps) {
           }
         />
       </div>
+      <FormSheet open={templatesOpen} onOpenChange={setTemplatesOpen} width="xl" title="Templates" description="Reusable sequences and steps. A template is a copy: changing one never changes a sequence built from it.">
+        {templatesOpen ? (
+          <Tabs defaultValue="sequences">
+            <TabsList aria-label="Template kind">
+              <TabsTrigger value="sequences">Sequence templates</TabsTrigger>
+              <TabsTrigger value="steps">Step templates</TabsTrigger>
+            </TabsList>
+            <TabsContent value="sequences" className="pt-3">
+              <SequenceTemplates onUse={(t) => { setPrefill({ name: t.name, steps: t.steps }); setTemplatesOpen(false); setCreating(true); }} />
+            </TabsContent>
+            <TabsContent value="steps" className="pt-3"><StepTemplates /></TabsContent>
+          </Tabs>
+        ) : null}
+      </FormSheet>
       <FormSheet open={creating} onOpenChange={setCreating} width="xl" title="New sequence" description="Saved as a draft. Nobody is contacted until you launch it.">
         {creating ? (
           <SequenceBuilder
+            key={prefill ? `tpl:${prefill.name}` : "blank"}
+            initialName={prefill?.name}
+            initialSteps={prefill?.steps}
             ownerEmail={ownerEmail}
             onSaved={(id) => { setCreating(false); refreshList(); open(id); }}
           />

package/blocks/sequencer/components/step-ai-assist.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+/**
+ * StepAiAssist: AI help for the copy of ONE email or LinkedIn step. It is collapsed until opened and loads nothing
+ * until then. Plug it into StepEditor's `renderAssist` slot (SequenceBuilder does).
+ *
+ * SDK operations, in order:
+ *   Improve the instructions (email steps the AI writes)
+ *     POST /sequencer/content/instructions/improve  (sequences.improveStepInstruction)  BILLABLE -> ConfirmSpendDialog first.
+ *     Returns a rewrite of your instruction; it is shown beside yours and only replaces it when you accept.
+ *   Preview a draft for one contact
+ *     GET  /contacts?name=                           (contacts.listContacts)           read   - find the contact
+ *     GET  /sequencer/agents/textual                 (sequences.listSequencerTextualAgents)  read - the agent that writes
+ *     POST /sequencer/content/email/estimate         (sequences.estimateEmailDraft)    read, FREE - the credit price, shown in the dialog
+ *     POST /sequencer/content/email/generate         (sequences.draftEmail)            BILLABLE -> ConfirmSpendDialog first
+ *     POST /sequencer/content/linkedin/generate      (sequences.draftLinkedinMessage)  BILLABLE -> ConfirmSpendDialog first
+ *     The draft is shown, never sent or saved. "Use as my copy" first warns that the draft is personalised for one contact while the step goes to everyone, and writes it only after a second click.
+ * Nothing here reaches a contact: it only drafts text for you to read.
+ */
+import { useEffect, useState } from "react";
+import { Sparkles } from "lucide-react";
+import { Button, Input, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { agentOptions, draftContact, readCreditEstimate, readEmailDraft, readImprovedInstruction, readLinkedinDraft, templateRows } from "../lib/sequencer-manage";
+import type { DraftContact } from "../lib/sequencer-manage";
+import type { DraftStep } from "../lib/sequencer-utils";
+
+export interface StepAiAssistProps {
+  step: DraftStep;
+  onChange: (next: DraftStep) => void;
+  /** The saved sequence this step belongs to, when there is one (gives the drafter the earlier steps as context). */
+  sequenceId?: string;
+  /** 1-based position of the step, for the same reason. */
+  stepOrder?: number;
+  className?: string;
+}
+
+const LINKEDIN_COPY: Record<string, string | undefined> = { CONNECTION_REQUEST: "linkedin_connection_message", MESSAGE: "linkedin_message_text", INMAIL: "linkedin_inmail_body" };
+const text = (v: unknown): string => (typeof v === "string" ? v : "");
+
+function useDebounced<T>(value: T, ms = 300): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}
+
+type Pending = { kind: "improve" } | { kind: "draft"; credits: number | null; cached: boolean } | null;
+
+export function StepAiAssist({ step, onChange, sequenceId, stepOrder, className }: StepAiAssistProps) {
+  const [open, setOpen] = useState(false);
+  if (step.kind !== "email" && step.kind !== "linkedin") return null;
+  if (!open) {
+    return <div className={className}><Button type="button" size="sm" variant="ghost" onClick={() => setOpen(true)}><Sparkles className="mr-1 size-4" aria-hidden />AI help for this step</Button></div>;
+  }
+  return <AssistPanel step={step} onChange={onChange} sequenceId={sequenceId} stepOrder={stepOrder} onClose={() => setOpen(false)} className={className} />;
+}
+
+function AssistPanel({ step, onChange, sequenceId, stepOrder, onClose, className }: StepAiAssistProps & { onClose: () => void }) {
+  const isEmail = step.kind === "email";
+  const action = text(step.step_data.linkedin_action_type);
+  const copyKey = LINKEDIN_COPY[action];
+  const aiEmail = isEmail && step.input_type !== "MANUAL_TEMPLATE";
+  const [instructions, setInstructions] = useState(text(step.step_data.instructions));
+  const [agent, setAgent] = useState("");
+  const [search, setSearch] = useState("");
+  const [contact, setContact] = useState<DraftContact | null>(null);
+  const [pending, setPending] = useState<Pending>(null);
+  const [improved, setImproved] = useState<string | null>(null);
+  const [draft, setDraft] = useState<{ subject: string; body: string } | null>(null);
+  // The draft is written for ONE contact but the step is sent to every contact: ask before it replaces the step copy.
+  const [confirmingCopy, setConfirmingCopy] = useState(false);
+  const q = useDebounced(search.trim());
+
+  const agents = useG8Query(async (signal) => agentOptions(await g8Get("/sequencer/agents/textual", undefined, { signal })), []);
+  const found = useG8Query(
+    async (signal) => templateRows<Record<string, unknown>>(await g8Get("/contacts", { name: q, limit: 8 }, { signal })).map(draftContact).filter((c): c is DraftContact => c != null),
+    [q],
+    { enabled: q.length >= 2 },
+  );
+
+  const body = () =>
+    isEmail
+      ? { agent_name: agent, contact_id: contact!.id, contact_work_email: contact!.email, first_name: contact!.first_name, last_name: contact!.last_name, instructions, lead_info: contact!.lead_info, sequence_id: sequenceId, step_order: stepOrder }
+      : { agent_name: agent, contact_id: contact!.id, first_name: contact!.first_name, last_name: contact!.last_name, linkedin_action_type: action, instructions, lead_info: contact!.lead_info };
+
+  const prepare = useG8Mutation(async (kind: "improve" | "draft") => {
+    if (kind === "improve") return setPending({ kind: "improve" });
+    // The estimate is free and exact; if it is unavailable the dialog still asks, without a number.
+    const estimate = isEmail ? await g8Post("/sequencer/content/email/estimate", body()).then(readCreditEstimate, () => null) : null;
+    setPending({ kind: "draft", credits: estimate?.credits ?? null, cached: estimate?.cached ?? false });
+  });
+  const run = useG8Mutation(async (p: NonNullable<Pending>) => {
+    if (p.kind === "improve") {
+      setImproved(readImprovedInstruction(await g8Post("/sequencer/content/instructions/improve", { user_instruction: instructions })) || null);
+    } else if (isEmail) {
+      setDraft(readEmailDraft(await g8Post("/sequencer/content/email/generate", body())));
+    } else {
+      const li = readLinkedinDraft(await g8Post("/sequencer/content/linkedin/generate", body()));
+      setDraft(li ? { subject: li.subject, body: li.message } : null);
+    }
+    setPending(null);
+  }, { onError: () => setPending(null) });
+
+  const useCopy = () => {
+    if (!draft) return;
+    const data = isEmail ? { ...step.step_data, subject: draft.subject, body: draft.body } : { ...step.step_data, ...(copyKey ? { [copyKey]: draft.body } : {}), ...(action === "INMAIL" && draft.subject ? { linkedin_inmail_subject: draft.subject } : {}) };
+    onChange({ ...step, dirty: true, input_type: "MANUAL_TEMPLATE", step_data: data });
+    setDraft(null);
+    setConfirmingCopy(false);
+  };
+  const acceptInstructions = () => {
+    if (improved == null) return;
+    setInstructions(improved);
+    onChange({ ...step, dirty: true, step_data: { ...step.step_data, instructions: improved } });
+    setImproved(null);
+  };
+
+  const canDraft = Boolean(agent) && contact != null && instructions.trim().length > 0 && (isEmail ? Boolean(contact.email) : Boolean(copyKey));
+  const busy = prepare.loading || run.loading;
+  const confirmDraft = pending?.kind === "draft" ? pending : null;
+
+  return (
+    <div className={`space-y-3 rounded-md border border-border p-3 text-sm ${className ?? ""}`} aria-label="AI help">
+      <div className="flex items-center justify-between"><h4 className="font-medium">AI help</h4><Button type="button" size="sm" variant="ghost" onClick={onClose}>Close</Button></div>
+      <Textarea aria-label="What should it say" rows={3} placeholder="What should this message say, and to whom?" value={instructions} onChange={(e) => setInstructions(e.target.value)} />
+      {aiEmail ? <Button type="button" size="sm" variant="outline" disabled={!instructions.trim() || busy} onClick={() => void prepare.mutate("improve")}>Improve my instructions</Button> : null}
+      {improved != null ? (
+        <div role="group" aria-label="Improved instructions" className="space-y-2 rounded-md bg-muted p-2">
+          <p className="whitespace-pre-wrap">{improved}</p>
+          <div className="flex gap-2"><Button type="button" size="sm" onClick={acceptInstructions}>Use these instructions</Button><Button type="button" size="sm" variant="ghost" onClick={() => setImproved(null)}>Keep mine</Button></div>
+        </div>
+      ) : null}
+
+      <div className="space-y-2 border-t border-border pt-3">
+        <p className="font-medium">Preview a draft for one contact</p>
+        <select aria-label="Agent" className="h-9 w-full rounded-md border border-border bg-background px-2" value={agent} disabled={agents.loading} onChange={(e) => setAgent(e.target.value)}>
+          <option value="">{agents.loading ? "Loading agents..." : "Choose the agent that writes"}</option>
+          {(agents.data ?? []).map((a) => <option key={a.value} value={a.value}>{a.label}</option>)}
+        </select>
+        {agents.error ? <ApiError error={agents.error} title="Could not load the agents" onRetry={() => void agents.refetch()} /> : null}
+        {agents.data && agents.data.length === 0 ? <p className="text-muted-foreground">No agent is set up yet, so there is nobody to write the draft.</p> : null}
+        {contact ? (
+          <p className="flex items-center justify-between gap-2"><span>Draft for <strong>{contact.label}</strong></span><Button type="button" size="sm" variant="ghost" onClick={() => setContact(null)}>Change</Button></p>
+        ) : (
+          <>
+            <Input aria-label="Find a contact" placeholder="Search contacts by name" value={search} onChange={(e) => setSearch(e.target.value)} />
+            {found.error ? <ApiError error={found.error} compact onRetry={() => void found.refetch()} /> : null}
+            {found.data && found.data.length === 0 ? <p className="text-muted-foreground">No contact matches.</p> : null}
+            {found.data && found.data.length > 0 ? (
+              <ul aria-label="Contacts" className="divide-y rounded-md border border-border">
+                {found.data.map((c) => <li key={c.id}><button type="button" className="w-full p-2 text-left hover:bg-muted/50" onClick={() => setContact(c)}>{c.label}</button></li>)}
+              </ul>
+            ) : null}
+          </>
+        )}
+        {!isEmail && !copyKey ? <p className="text-muted-foreground">This LinkedIn action sends no text, so there is nothing to draft.</p> : null}
+        <Button type="button" size="sm" disabled={!canDraft || busy} loading={prepare.loading} onClick={() => void prepare.mutate("draft")}>Draft for this contact</Button>
+      </div>
+
+      {[prepare.error, run.error].map((e, i) => (e ? <ApiError key={i} error={e} title="The AI request failed" /> : null))}
+      {draft ? (
+        <div role="group" aria-label="Drafted copy" className="space-y-2 rounded-md bg-muted p-2">
+          {draft.subject ? <p className="font-medium">{draft.subject}</p> : null}
+          <p className="whitespace-pre-wrap">{draft.body}</p>
+          <div className="flex gap-2">{confirmingCopy ? (
+            <div role="alert" className="space-y-2 rounded-md border border-border bg-background p-2">
+              <p>This draft was written for {contact?.label ?? "one contact"}. The step is sent to every contact in the sequence, so names and details in it will go to people they do not fit. Replace the step copy only if you will make it generic (merge tokens such as {"{{first_name}}"}).</p>
+              <div className="flex gap-2"><Button type="button" size="sm" onClick={useCopy}>Replace the step copy</Button><Button type="button" size="sm" variant="ghost" onClick={() => setConfirmingCopy(false)}>Keep my copy</Button></div>
+            </div>
+          ) : (
+            <div className="flex gap-2"><Button type="button" size="sm" onClick={() => setConfirmingCopy(true)}>Use as my copy</Button><Button type="button" size="sm" variant="ghost" onClick={() => { setDraft(null); setConfirmingCopy(false); }}>Discard</Button></div>
+          )}</div>
+        </div>
+      ) : null}
+
+      <ConfirmSpendDialog
+        open={pending != null}
+        tier="billable"
+        title={pending?.kind === "improve" ? "Improve these instructions with AI?" : `Draft ${isEmail ? "an email" : "a LinkedIn message"} for ${contact?.label ?? "this contact"}?`}
+        description={pending?.kind === "improve" ? "The AI rewrites your instructions. It uses credits and nothing is sent to anyone." : confirmDraft?.cached ? "An identical draft is cached, so this one is free. Nothing is sent to anyone." : "The AI writes one draft for you to read. It uses credits each time and nothing is sent to anyone."}
+        estimatedCredits={confirmDraft?.credits ?? undefined}
+        confirmLabel={pending?.kind === "improve" ? "Improve instructions" : "Write draft"}
+        confirming={run.loading}
+        onConfirm={() => pending && void run.mutate(pending)}
+        onCancel={() => setPending(null)}
+      />
+    </div>
+  );
+}

package/blocks/sequencer/components/step-editor.tsx

@@ -15,6 +15,7 @@
  * Problems show inline and `stepIssues(step)` returns the same list for gating a Save button.
  */
 
+import type { ReactNode } from "react";
 import { Input, Textarea } from "@graph8/sdk/ui";
 import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
@@ -28,6 +29,10 @@ export interface StepEditorProps {
   index: number;
   onChange: (next: DraftStep) => void;
   onRemove?: () => void;
+  /** Optional slot under the copy, for AI help or other tools (SequenceBuilder passes StepAiAssist). Receives the step and its setter. */
+  /** Disable the Manual / AI input-type select (a saved step template: the API fixes its input type at creation). */
+  lockInputType?: boolean;
+  renderAssist?: (step: DraftStep, onChange: (next: DraftStep) => void) => ReactNode;
   disabled?: boolean;
   className?: string;
 }
@@ -52,15 +57,15 @@ function LinkedinReadiness() {
   const c = conn.data?.data;
   if (conn.loading || conn.error || !c) return null;
   if (c.connected && c.is_token_valid !== false && !c.requires_manual_login)
-    return <p className="text-xs text-green-700">LinkedIn sender connected.</p>;
+    return <p className="text-xs text-positive-foreground">LinkedIn sender connected.</p>;
   return (
-    <p role="alert" className="text-xs text-amber-800">
+    <p role="alert" className="text-xs text-warning-foreground">
       LinkedIn is not ready to send. Reconnect the LinkedIn account in the {brand.linkLabel} app before launching.
     </p>
   );
 }
 
-export function StepEditor({ step, index, onChange, onRemove, disabled, className }: StepEditorProps) {
+export function StepEditor({ step, index, onChange, onRemove, renderAssist, lockInputType, disabled, className }: StepEditorProps) {
   const set = (patch: Record<string, unknown>) => onChange({ ...step, dirty: true, step_data: { ...step.step_data, ...patch } });
   const issues = stepIssues(step);
   const data = step.step_data;
@@ -72,13 +77,13 @@ export function StepEditor({ step, index, onChange, onRemove, disabled, classNam
   const phoneOptions = Array.isArray(data.phone_options) ? (data.phone_options as string[]) : [];
 
   return (
-    <fieldset disabled={disabled} className={`space-y-3 rounded border border-gray-200 p-3 ${className ?? ""}`} data-step-kind={step.kind}>
+    <fieldset disabled={disabled} className={`space-y-3 rounded border border-border p-3 ${className ?? ""}`} data-step-kind={step.kind}>
       <div className="flex items-center justify-between">
-        <legend className="text-sm font-semibold">
+        <legend className="text-sm font-medium">
           Step {index}: {KIND_LABEL[step.kind]}
         </legend>
         {onRemove ? (
-          <button type="button" className="text-xs text-red-700 hover:underline" onClick={onRemove}>
+          <button type="button" className="text-xs text-error-foreground hover:underline" onClick={onRemove}>
             Remove step
           </button>
         ) : null}
@@ -105,8 +110,9 @@ export function StepEditor({ step, index, onChange, onRemove, disabled, classNam
             Copy
             <select
               aria-label="Email copy"
-              className="ml-2 h-8 rounded border border-gray-300 px-1 text-sm"
+              className="ml-2 h-8 rounded border border-input px-1 text-sm"
               value={step.input_type}
+              disabled={lockInputType}
               onChange={(e) => onChange({ ...step, dirty: true, input_type: e.target.value as InputType })}
             >
               <option value="MANUAL_TEMPLATE">I write it</option>
@@ -114,6 +120,7 @@ export function StepEditor({ step, index, onChange, onRemove, disabled, classNam
               <option value="ON_DEMAND">AI writes each email</option>
             </select>
           </label>
+          {lockInputType ? <p className="text-xs text-muted-foreground">The input type is fixed once a template is created. Create a new template to change it.</p> : null}
           {step.input_type === "MANUAL_TEMPLATE" ? (
             <>
               <Input aria-label="Subject" placeholder="Subject" value={str("subject")} onChange={(e) => set({ subject: e.target.value })} />
@@ -141,7 +148,7 @@ export function StepEditor({ step, index, onChange, onRemove, disabled, classNam
         <>
           <select
             aria-label="LinkedIn action"
-            className="h-8 rounded border border-gray-300 px-1 text-sm"
+            className="h-8 rounded border border-input px-1 text-sm"
             value={action}
             onChange={(e) => set({ linkedin_action_type: e.target.value })}
           >
@@ -160,7 +167,7 @@ export function StepEditor({ step, index, onChange, onRemove, disabled, classNam
               onChange={(e) => set({ [copyKey]: e.target.value })}
             />
           ) : (
-            <p className="text-xs text-gray-500">This action sends no text.</p>
+            <p className="text-xs text-muted-foreground">This action sends no text.</p>
           )}
           {action === "INMAIL" ? (
             <Input
@@ -176,7 +183,7 @@ export function StepEditor({ step, index, onChange, onRemove, disabled, classNam
 
       {step.kind === "call" || step.kind === "task" ? (
         <div className="space-y-1 text-sm">
-          <p className="text-gray-600">
+          <p className="text-muted-foreground">
             {step.kind === "call" ? "An automatic call attempt." : "Creates a call task for a person to work in the dialer."}
           </p>
           <div className="flex flex-wrap gap-3">
@@ -198,13 +205,15 @@ export function StepEditor({ step, index, onChange, onRemove, disabled, classNam
         </div>
       ) : null}
 
+      {renderAssist ? renderAssist(step, onChange) : null}
+
       {broken ? (
-        <p role="alert" className="text-xs text-amber-800">
+        <p role="alert" className="text-xs text-warning-foreground">
           A {"{{merge token}}"} is not closed. Unclosed tokens are deleted when the email sends.
         </p>
       ) : null}
       {issues.length > 0 ? (
-        <ul className="text-xs text-red-700" aria-label="Step problems">
+        <ul className="text-xs text-error-foreground" aria-label="Step problems">
           {issues.map((i) => (
             <li key={i}>{i}</li>
           ))}