Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(content-editor): hand the page off to Content Agent from Quality, in one run (CE-051, part 3) (#1484)

Cihandfc768e81232
diff --git a/web/messages/en.json b/web/messages/en.json
index 076dcd381..7e2a8cd6c 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -3802,6 +3802,8 @@
"steps": {
"readRules": "Reading {count, plural, one {# rule} other {# rules}}",
"readRulesAny": "Reading rules",
+ "readChecks": "Reading {count, plural, one {# check} other {# checks}}",
+ "readChecksAny": "Reading checks",
"gatherSources": "Gathering {count, plural, one {# source} other {# sources}}",
"gatherSourcesAny": "Gathering sources",
"writeChanges": "Writing {count, plural, one {# change} other {# changes}}",
@@ -3892,6 +3894,10 @@
"open_suggestions": "This page has open suggestions, maybe from another tab. They're shown now: accept or reject them first.",
"published": "This page is published. Content Agent suggests changes to drafts only.",
"writing": "Content Agent is already writing this page, maybe from another tab. Try again once it has finished.",
+ "running": "Content Agent is already fixing this page, maybe from another tab. Try again once it has finished.",
+ "not_due": "This brand doesn't hand off quality fixes on its own.",
+ "already": "Content Agent already had this page's automatic hand-off.",
+ "off": "Hand off isn't available on this workspace yet.",
"failed": "Content Agent couldn't run. Try again."
}
},
@@ -4844,6 +4850,15 @@
"keep": "Keep",
"aiCheck": "AI check",
"yourBrand": "your brand",
+ "handOff": {
+ "title": "Hand it off to Content Agent",
+ "line": "Fixes {count, plural, one {# suggestion} other {# suggestions}} in one run, for you to review · {todos, plural, =0 {nothing left for you} one {# to-do stays yours} other {# to-dos stay yours}}",
+ "nothing": "Nothing for the agent to fix · {todos, plural, =0 {nothing left for you} one {# to-do stays yours} other {# to-dos stay yours}}",
+ "button": "Hand off",
+ "running": "Working…",
+ "reading": "The page is still being read: hand it off once Quality has its scores.",
+ "doneMax": "Content Agent suggested {count} changes, the most one run makes · review them, then hand it off again for the suggestions still open"
+ },
"addSource": "Add source",
"addSourceTo": "Add a source to “{claim}”",
"addProof": "Add proof link",
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx
index b46980b65..9eea1649a 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_draft-editor.tsx
@@ -3,7 +3,7 @@
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { useFormatter, useTranslations } from 'next-intl';
import { toast } from 'sonner';
-import { EditorContent, useEditor } from '@tiptap/react';
+import { EditorContent, useEditor, type Editor } from '@tiptap/react';
import type { Node as PmNode } from '@tiptap/pm/model';
import { TextSelection, type Transaction } from '@tiptap/pm/state';
import StarterKit from '@tiptap/starter-kit';
@@ -34,6 +34,8 @@ import { updateBrand } from '@/lib/actions/brand';
import {
decideDraftSuggestions,
fixDraftRules,
+ handOffDraft,
+ type HandOffError,
getCitedPassages,
getDraftSuggestions,
keepAgentBeforeVersion,
@@ -89,6 +91,7 @@ import { PAGE_READ_DELAY_MS, draftTitleFromDoc, safeLinkHref } from '@/lib/conte
import { JsonLd } from '@/lib/content/json-ld-node';
import { firstImage, isArticlePage } from '@/lib/content/page-schema';
import { PLACEHOLDER, pagePlaceholders, placeholderIn } from '@/lib/content/placeholders';
+import { HANDOFF_KEYS, handOffItems } from '@/lib/content/hand-off';
import {
blankCode,
bylineText,
@@ -189,7 +192,7 @@ import {
wordsUnderTitle,
writeSkips,
} from './_next-step';
-import { useTodoCopy, type QualityRead } from './_quality-tab';
+import { qualitySuggestions, useTodoCopy, type HandOff, type QualityRead } from './_quality-tab';
import { PageTypeMenu } from './_page-type-menu';
import type { AgentRewrite } from './_brief-tab';
import { ruleStatusDetail, type AgentFix, type PageRewrite } from './_rules-tab';
@@ -249,7 +252,8 @@ const DOCUMENT_CLASS = cn(
const FIX_WAIT_MS = 90_000;
/** The runs the agent card shows: Fix open rules', or the brief's. */
-const FIX_RUNS = ['fix'] as const;
+// Fix open rules, and Quality's hand-off (CE-051): the same card, steps and Stop.
+const FIX_RUNS = ['fix', 'handoff'] as const;
const BRIEF_RUNS = ['brief'] as const;
/**
@@ -1735,23 +1739,43 @@ export function DraftEditor({
.join(' · '),
};
}),
- textRules: rules.textRules.filter(({ rule }) => rule.on).map(({ rule }) => rule.text),
- locked: (() => {
- const locks = citedLocks(editor.state);
- return [...locks.labels.keys()].filter((key) => !locks.unlocked.has(key));
- })(),
- // The data it writes from: the sources the Sources tab keeps (CE-033).
- ...(reads.sources?.data
- ? {
- sources: rebuildSources(reads.sources.data, reads.sources.choices, {
- title,
- sourceUrl: draft.sourceUrl,
- html: editor.getHTML(),
- length: rules.length,
- }),
- }
- : {}),
+ ...agentContext(editor),
};
+ await runAgentFix(() => fixDraftRules(draft.id, draft.brandId, request));
+ };
+
+ /**
+ * What every fix by the agent sends besides its rules: the person's own
+ * rules, the locked passages, and the sources the Sources tab keeps, which
+ * it writes from (CE-033).
+ */
+ const agentContext = (ed: Editor) => ({
+ textRules: rules.textRules.filter(({ rule }) => rule.on).map(({ rule }) => rule.text),
+ locked: (() => {
+ const locks = citedLocks(ed.state);
+ return [...locks.labels.keys()].filter((key) => !locks.unlocked.has(key));
+ })(),
+ ...(reads.sources?.data
+ ? {
+ sources: rebuildSources(reads.sources.data, reads.sources.choices, {
+ title,
+ sourceUrl: draft.sourceUrl,
+ html: ed.getHTML(),
+ length: rules.length,
+ }),
+ }
+ : {}),
+ });
+
+ /**
+ * One of the agent's fixes from this page (Fix open rules, Hand off): the
+ * page is saved, the agent leaves a new batch of suggestions for review,
+ * and Stop or a lost answer is said as such.
+ */
+ const runAgentFix = async (
+ send: () => Promise<{ count: number } | { error: HandOffError }>,
+ told: (count: number) => string = fixedMessage,
+ ) => {
setStoppingRun(null);
stopSent.current = null;
setFixing(true);
@@ -1759,7 +1783,7 @@ export function DraftEditor({
try {
// The agent reads the page as saved.
await autosave.settle();
- const result = await fixDraftRules(draft.id, draft.brandId, request).catch((err) => {
+ const result = await send().catch((err) => {
// The call itself gave up (a timeout on the way): the agent may still finish.
console.error('Failed to hear back from the Content Agent:', err);
return { error: 'unconfirmed' as const };
@@ -1780,7 +1804,7 @@ export function DraftEditor({
setSuggestions(landed);
setBarClosed(false);
agentBeforeKept.current = false;
- toast.success(fixedMessage(landed.filter((s) => s.status === 'open').length));
+ toast.success(told(landed.filter((s) => s.status === 'open').length));
nudgeAt('agent');
return;
}
@@ -1806,7 +1830,7 @@ export function DraftEditor({
setBarClosed(false);
// A new batch: History keeps the page again before its first change.
agentBeforeKept.current = false;
- toast.success(fixedMessage(result.count));
+ toast.success(told(result.count));
nudgeAt('agent');
} catch (err) {
console.error('Failed to run the Content Agent:', err);
@@ -1818,6 +1842,49 @@ export function DraftEditor({
}
};
+ // Hand it off to Content Agent (Quality spec §5, CE-051): Quality's open
+ // suggestions, each with what it names on the page; the disclosure only
+ // with its line in the page's language.
+ const tQuality = useTranslations('contentEditor.editor.quality');
+ const handOffSuggestions = sourcesOn && quality ? qualitySuggestions(tQuality, quality) : [];
+ const handOffList = handOffItems(handOffSuggestions, {
+ // Added, and not read again yet: never a second one.
+ disclosureLine: disclosureOnPage ? null : disclosureLine,
+ });
+ // What AI read of the page (Answer first, the disclosure, balance) is read
+ // again after each save (usePageRead's reading): until then a fix it
+ // asked for may be on the page.
+ const handOffWaitsForRead = handOffSuggestions.some((s) => s.ai && HANDOFF_KEYS.has(s.key));
+ const [handingOff, setHandingOff] = useState(false);
+ const handedOff = (count: number) =>
+ count >= AGENT_RUN_MAX ? tQuality('handOff.doneMax', { count }) : fixedMessage(count);
+ /**
+ * The agent fixes the page's open Quality suggestions in one run, as
+ * suggestions to review; the to-dos stay the person's (one run, on the
+ * workspace's AI usage).
+ */
+ const handOff = async (origin: 'person' | 'auto' = 'person') => {
+ if (!editor || fixing || starting || rewriting || !citedRead) return;
+ if (openSuggestions > 0) {
+ toast(t('suggestions.decideFirst', { count: openSuggestions }));
+ return;
+ }
+ if (handOffList.length === 0) {
+ toast(t('suggestions.nothingToFix'));
+ return;
+ }
+ const items = handOffList;
+ setHandingOff(true);
+ try {
+ await runAgentFix(
+ () => handOffDraft(draft.id, draft.brandId, { items, origin, ...agentContext(editor) }),
+ handedOff,
+ );
+ } finally {
+ setHandingOff(false);
+ }
+ };
+
// The agent at work from this page: Fix open rules, or the brief. Its run,
// step by step, and Stop (CE-027/035).
const agentWorking = fixing || briefRebuilding;
@@ -1898,20 +1965,43 @@ export function DraftEditor({
.setMeta('addToHistory', false),
);
}, [editor, spotList, t]);
+ // Fix open rules and Hand off share the agent's fix run (fixing): each
+ // card runs its own, and the other's run is the agent at work.
+ const fixRunning = fixing && !handingOff;
+ const handOffRunning = fixing && handingOff;
+ /** Why the agent's fix can't run now, said on the card whose run isn't the one under way. */
+ const agentFixBlocked = (running: boolean) =>
+ aiUsedUp && !running
+ ? aiUsedUp
+ : openSuggestions > 0
+ ? t('suggestions.decideFirst', { count: openSuggestions })
+ : !citedRead
+ ? t('suggestions.citedLoading')
+ : agentBusy && !running
+ ? t('suggestions.agentBusy')
+ : null;
const agentFix: AgentFix = {
run: (only) => void fixRules(only),
- running: fixing,
- blocked:
- aiUsedUp && !fixing
- ? aiUsedUp
- : openSuggestions > 0
- ? t('suggestions.decideFirst', { count: openSuggestions })
- : !citedRead
- ? t('suggestions.citedLoading')
- : agentBusy && !fixing
- ? t('suggestions.agentBusy')
- : null,
+ running: fixRunning,
+ blocked: agentFixBlocked(fixRunning),
};
+ const handOffCard: HandOff | null =
+ sourcesOn && quality
+ ? {
+ run: () => void handOff(),
+ running: handOffRunning,
+ // As Fix's, and not while the page's reads would still move the list:
+ // the claims; the page's read before its first answer, or while a
+ // fix of what AI read of it may be on the page (it reads each save).
+ blocked:
+ agentFixBlocked(handOffRunning) ??
+ (claimsRead.reading || (pageRead.reading && (!pageRead.read || handOffWaitsForRead))
+ ? tQuality('handOff.reading')
+ : null),
+ count: handOffList.length,
+ todos: quality.todos.filter((todo) => !todo.done).length,
+ }
+ : null;
// The card's Run Agent says why it won't run, as the Rules card does: also
// when the only rules left open are ones the agent doesn't fix (one H1).
const agentRules = openRulesForAgent(rules.rules);
@@ -3080,6 +3170,7 @@ export function DraftEditor({
onShowPlaceholder={showFirstPlaceholder}
onPickAuthor={() => setAuthorMenuOpen(true)}
onPickReviewer={() => setReviewerMenuOpen(true)}
+ handOff={handOffCard}
yourInput={inputsRead.status === 'off' ? null : inputsRead}
onAddInput={addInput}
onConfirmAuthor={confirmAuthor}
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx
index 0b810636f..76b3ed213 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.test.tsx
@@ -1,6 +1,6 @@
import { act } from 'react';
import { createRoot, type Root } from 'react-dom/client';
-import { NextIntlClientProvider } from 'next-intl';
+import { createTranslator, NextIntlClientProvider } from 'next-intl';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import messages from '../../../../../../../../messages/en.json';
import { eeat, trust, trustBlocks, type LinkCheck } from '@/lib/content/quality-checks';
@@ -15,8 +15,9 @@ vi.mock('@/i18n/navigation', () => ({
),
}));
-const { QualityTab } = await import('./_quality-tab');
+const { QualityTab, qualitySuggestions } = await import('./_quality-tab');
type QualityRead = import('./_quality-tab').QualityRead;
+type HandOff = import('./_quality-tab').HandOff;
/**
* Instructions › Quality (Quality spec §3, CE-039): the scores, their label,
@@ -97,7 +98,7 @@ const onAddImage = vi.fn();
const onPickReviewer = vi.fn();
const onConfirmAuthor = vi.fn();
-async function render(quality: QualityRead | Readability | null) {
+async function render(quality: QualityRead | Readability | null, handOff: HandOff | null = null) {
const q = quality && 'eeat' in quality ? quality : read(quality as Readability | null);
await act(async () => {
root.render(
@@ -113,6 +114,7 @@ async function render(quality: QualityRead | Readability | null) {
onConfirmImages={onConfirmImages}
onAddImage={onAddImage}
onPickReviewer={onPickReviewer}
+ handOff={handOff}
onConfirmAuthor={onConfirmAuthor}
/>
</NextIntlClientProvider>,
@@ -567,6 +569,70 @@ describe('QualityTab', () => {
);
});
+ it('hands the suggestions off in one run, the to-dos staying the person’s (CE-051)', async () => {
+ const run = vi.fn();
+ const handOff = { run, running: false, blocked: null, count: 3, todos: 2 };
+ await render(null, handOff);
+ const card = container.querySelector('[aria-label="Hand it off to Content Agent"]')!;
+ expect(card.textContent).toContain(
+ 'Fixes 3 suggestions in one run, for you to review · 2 to-dos stay yours',
+ );
+ const button = [...card.querySelectorAll('button')].find((b) => b.textContent === 'Hand off')!;
+ await act(async () => button.click());
+ expect(run).toHaveBeenCalled();
+
+ // Blocked: it says why, on the button too; running: it says so; nothing to fix: it can't run.
+ await render(null, { ...handOff, blocked: 'Decide the 2 open suggestions first.' });
+ const held = [...container.querySelectorAll('button')].find(
+ (b) => b.textContent === 'Hand off',
+ )!;
+ expect(held.disabled).toBe(true);
+ const why = held.getAttribute('aria-describedby');
+ expect([...container.querySelectorAll('p')].find((p) => p.id === why)?.textContent).toBe(
+ 'Decide the 2 open suggestions first.',
+ );
+ await render(null, { ...handOff, running: true });
+ expect(container.textContent).toContain('Working…');
+ await render(null, { ...handOff, count: 0, todos: 0 });
+ expect(container.textContent).toContain('Nothing for the agent to fix · nothing left for you');
+ // Below phase 2: no card.
+ await render(null);
+ expect(container.querySelector('[aria-label="Hand it off to Content Agent"]')).toBeNull();
+ });
+
+ it('leaves the person a suggestion that asks the other way to the hand-off’s checks (CE-051)', () => {
+ const t = createTranslator({
+ locale: 'en',
+ messages,
+ namespace: 'contentEditor.editor.quality',
+ }) as unknown as Parameters<typeof qualitySuggestions>[0];
+ const byKey = (readability: Readability) =>
+ new Map(qualitySuggestions(t, read(readability)).map((s) => [s.key, s]));
+ // Sentences too short, a page too simple (over the band): longer and harder are the person's.
+ const simple = byKey({
+ ...result,
+ checks: result.checks.map((c) =>
+ c.id === 'avgSentence' ? { ...c, points: 10, value: 9, count: -1 } : c,
+ ),
+ });
+ expect(simple.get('readability:avgSentence')?.handOff).toBe(false);
+ expect(simple.get('readability:readingLevel')?.handOff).toBe(false);
+ expect(simple.get('readability:longSentences')?.handOff).toBeUndefined();
+ // Too long, too hard: the agent's.
+ const hard = byKey({
+ ...result,
+ checks: result.checks.map((c) =>
+ c.id === 'avgSentence'
+ ? { ...c, points: 10, value: 27, count: 1 }
+ : c.id === 'readingLevel'
+ ? { ...c, value: 40, count: -1 }
+ : c,
+ ),
+ });
+ expect(hard.get('readability:avgSentence')?.handOff).toBeUndefined();
+ expect(hard.get('readability:readingLevel')?.handOff).toBeUndefined();
+ });
+
it('asks a page that puts the brand forward to disclose it and add an honest weakness, AI checks, Show on the pick (CE-050)', async () => {
const PICK = 'Our top pick is the Acme Ridge 28.';
const result = trust({
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx
index 84fb127c8..26ef853dd 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_quality-tab.tsx
@@ -85,6 +85,17 @@ export interface QualityRead {
type ScoreName = 'eeat' | 'trust' | 'readability';
+/** Hand it off to Content Agent (Quality spec §5, CE-051), as the editor runs it. */
+export interface HandOff {
+ run: () => void;
+ running: boolean;
+ /** Why it can't run now (suggestions still open, AI usage spent, reads under way), or null. */
+ blocked: string | null;
+ /** The suggestions it fixes in one run, and the to-dos that stay the person's. */
+ count: number;
+ todos: number;
+}
+
export interface Suggestion {
key: string;
// E-E-A-T's are the person's to-dos.
@@ -100,6 +111,11 @@ export interface Suggestion {
claim?: ClaimMark;
/** Read by AI, not by rules alone: it says so (spec §3, "AI check"). */
ai?: boolean;
+ /**
+ * Hand off leaves it to the person (CE-051): it asks the other way to what
+ * the agent is told for its check (sentences too short, a page too simple).
+ */
+ handOff?: false;
}
/**
@@ -121,6 +137,7 @@ export function QualityTab({
onConfirmImages,
onAddImage,
onPickReviewer,
+ handOff = null,
onConfirmAuthor,
}: {
quality: QualityRead;
@@ -146,6 +163,8 @@ export function QualityTab({
onAddImage?: () => void;
/** Opens the header's reviewer menu (CE-049). */
onPickReviewer?: () => void;
+ /** Hand it off to Content Agent (CE-051): with Quality's phase 2. */
+ handOff?: HandOff | null;
}) {
const t = useTranslations('contentEditor.editor.quality');
const tSite = useTranslations('audit.siteTrust.checks');
@@ -159,16 +178,7 @@ export function QualityTab({
];
const { todos } = quality;
const todosLeft = todos.filter((todo) => !todo.done).length;
- const suggestions = [
- ...readabilitySuggestions(t, readability),
- ...trustSuggestions(t, trust, proofSentences(todos), {
- balanced: quality.aiChecks?.balanced ?? null,
- disclosure: quality.aiChecks?.disclosure ?? null,
- brand: quality.brandName,
- }),
- ]
- .filter((s) => s.gain > 0)
- .sort((a, b) => b.gain - a.gain);
+ const suggestions = qualitySuggestions(t, quality);
// Every live check has its points: none to raise, none of the person's left
// (a page too short to read says so instead).
const allDone = suggestions.length === 0 && todosLeft === 0 && readability?.score !== null;
@@ -206,6 +216,8 @@ export function QualityTab({
)}
</section>
+ {handOff && <HandOffCard handOff={handOff} />}
+
{todos.length > 0 && (
<section aria-label={t('todos.title')} className="space-y-2">
<h4 className="text-xs text-muted-foreground">
@@ -667,7 +679,68 @@ function readabilitySuggestions(t: T, readability: Readability | null): Suggesti
detail: detail(t, check),
show: check.at || null,
...(check.ai ? { ai: true } : {}),
+ ...(againstHandOff(check) ? { handOff: false as const } : {}),
+ }),
+ );
+}
+
+/** Asks for longer sentences or a harder read: the hand-off's checks say shorter and easier. */
+const againstHandOff = (check: ReadabilityCheck) =>
+ (check.id === 'avgSentence' && check.count < 0) ||
+ (check.id === 'readingLevel' && !!check.band && check.count > 0);
+
+/**
+ * What would raise the scores, the biggest gain first: Readability's and
+ * Trust's suggestions with a gain (E-E-A-T's are the person's to-dos). Hand
+ * off fixes these (CE-051).
+ */
+export function qualitySuggestions(t: T, quality: QualityRead): Suggestion[] {
+ return [
+ ...readabilitySuggestions(t, quality.readability),
+ ...trustSuggestions(t, quality.trust, proofSentences(quality.todos), {
+ balanced: quality.aiChecks?.balanced ?? null,
+ disclosure: quality.aiChecks?.disclosure ?? null,
+ brand: quality.brandName,
}),
+ ]
+ .filter((s) => s.gain > 0)
+ .sort((a, b) => b.gain - a.gain);
+}
+
+/**
+ * Hand it off to Content Agent (Quality spec §5, CE-051): one run fixes
+ * every suggestion, as suggestions to review; the to-dos stay the person's.
+ */
+function HandOffCard({ handOff }: { handOff: HandOff }) {
+ const t = useTranslations('contentEditor.editor.quality.handOff');
+ const whyId = useId();
+ const { count, todos, running, blocked, run } = handOff;
+ const why = blocked && !running && count > 0 ? blocked : null;
+ return (
+ <section aria-label={t('title')} className="space-y-2 rounded-xl border bg-card px-3 py-2.5">
+ <div className="flex items-start gap-3">
+ <div className="min-w-0 flex-1">
+ <h4 className="text-sm font-medium">{t('title')}</h4>
+ <p className="text-xs text-muted-foreground">
+ {count > 0 ? t('line', { count, todos }) : t('nothing', { todos })}
+ </p>
+ </div>
+ <Button
+ size="sm"
+ className="h-7 shrink-0"
+ disabled={running || count === 0 || !!blocked}
+ onClick={run}
+ aria-describedby={why ? whyId : undefined}
+ >
+ {running ? t('running') : t('button')}
+ </Button>
+ </div>
+ {why && (
+ <p id={whyId} className="text-xs text-amber-700 dark:text-amber-300">
+ {why}
+ </p>
+ )}
+ </section>
);
}
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_side-panel.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_side-panel.tsx
index 7cde5dbe8..f24393fc7 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_side-panel.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_side-panel.tsx
@@ -14,7 +14,7 @@ import { cn } from '@/lib/utils';
import { BriefTab, type AgentRewrite } from './_brief-tab';
import { DataNote, UsesYourData } from './_data-note';
import { ImpactTab } from './_impact-tab';
-import { QualityTab, type QualityRead } from './_quality-tab';
+import { QualityTab, type HandOff, type QualityRead } from './_quality-tab';
import { RulesTab, type AgentFix, type PageRewrite } from './_rules-tab';
import { SourcesTab } from './_sources-tab';
import { useBriefRebuild, type PageNow } from './_use-brief-rebuild';
@@ -139,6 +139,7 @@ export function EditorSidePanel({
onConfirmImages,
onAddImage,
onPickReviewer,
+ handOff = null,
}: {
draft: ContentDraft;
/** The brand's business type as the editor holds it (Quality CE-056). */
@@ -207,6 +208,8 @@ export function EditorSidePanel({
onAddImage?: () => void;
/** Quality's Pick reviewer: the header's reviewer menu (CE-049). */
onPickReviewer?: () => void;
+ /** Hand it off to Content Agent, Quality's (CE-051). */
+ handOff?: HandOff | null;
}) {
const t = useTranslations('contentEditor.editor.panel');
const tEditor = useTranslations('contentEditor.editor');
@@ -459,6 +462,7 @@ export function EditorSidePanel({
onConfirmImages={onConfirmImages}
onAddImage={onAddImage}
onPickReviewer={onPickReviewer}
+ handOff={handOff}
/>
</div>
)}
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx
index 9c3a46f05..0fe520858 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/page.test.tsx
@@ -64,6 +64,7 @@ const getDraftSuggestions = vi.fn();
const decideDraftSuggestions = vi.fn();
const keepAgentBeforeVersion = vi.fn();
const fixDraftRules = vi.fn();
+const handOffDraft = vi.fn();
const startAgentWriting = vi.fn();
const startPageRewrite = vi.fn();
vi.mock('@/lib/actions/brand-facts', () => ({
@@ -71,6 +72,7 @@ vi.mock('@/lib/actions/brand-facts', () => ({
}));
vi.mock('@/lib/actions/content-drafts', () => ({
fixDraftRules: (...args: unknown[]) => fixDraftRules(...args),
+ handOffDraft: (...args: unknown[]) => handOffDraft(...args),
startAgentWriting: (...args: unknown[]) => startAgentWriting(...args),
startPageRewrite: (...args: unknown[]) => startPageRewrite(...args),
getDraftSuggestions: (...args: unknown[]) => getDraftSuggestions(...args),
@@ -342,6 +344,7 @@ beforeEach(() => {
decideDraftSuggestions.mockReset().mockResolvedValue(1);
keepAgentBeforeVersion.mockReset().mockResolvedValue(undefined);
fixDraftRules.mockReset().mockResolvedValue({ count: 0 });
+ handOffDraft.mockReset().mockResolvedValue({ count: 0 });
startAgentWriting.mockReset().mockResolvedValue({ started: true });
startPageRewrite.mockReset().mockResolvedValue({ started: true });
localStorage.clear();
@@ -3082,6 +3085,62 @@ describe('the side panel', () => {
expect(done.textContent).toContain('The proof is linked');
});
+ it("hands the page's open Quality suggestions off to the agent in one run (CE-051)", async () => {
+ process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '2';
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ getContentAuthors.mockResolvedValue({
+ authors: [],
+ brands: [{ id: 'b1', name: 'Ledgerly' }],
+ me: { id: 'u1', role: 'admin' },
+ });
+ const long = `Teams ${Array.from({ length: 39 }, () => 'plan').join(' ')}.`;
+ getContentDraft.mockResolvedValue({
+ ...claimed,
+ bodyHtml: `${claimed.bodyHtml}<p>${long}</p>`,
+ });
+ let answer: (value: { count: number }) => void = () => {};
+ handOffDraft.mockReturnValue(new Promise((resolve) => (answer = resolve)));
+ window.innerWidth = 1440;
+ await renderPage();
+ await act(async () => void (await vi.advanceTimersByTimeAsync(3_000)));
+ const chip = [...container.querySelectorAll<HTMLButtonElement>('header button')].find((b) =>
+ b.textContent?.startsWith('Quality'),
+ )!;
+ await act(async () => chip.click());
+ const card = panel()!.querySelector('[aria-label="Hand it off to Content Agent"]')!;
+ expect(card.textContent).toContain('in one run, for you to review');
+ await act(async () =>
+ [...card.querySelectorAll<HTMLButtonElement>('button')]
+ .find((b) => b.textContent === 'Hand off')!
+ .click(),
+ );
+ await act(async () => void (await vi.advanceTimersByTimeAsync(0)));
+ expect(handOffDraft).toHaveBeenCalledWith(
+ 'd1',
+ 'b1',
+ expect.objectContaining({
+ origin: 'person',
+ items: expect.arrayContaining([
+ expect.objectContaining({
+ key: 'readability:longSentences',
+ detail: expect.stringContaining(long),
+ }),
+ ]),
+ }),
+ );
+ // Its card is the one working; Rules' Run Agent isn't, and waits for it.
+ expect(
+ [...card.querySelectorAll('button')].find((b) => b.textContent === 'Working…'),
+ ).toBeDefined();
+ await pickTab('Rules');
+ const others = [...panel()!.querySelectorAll('button')].filter((b) => !card.contains(b));
+ expect(others.some((b) => b.textContent?.includes('Working'))).toBe(false);
+ expect(others.find((b) => b.textContent === 'Run Agent')?.disabled).toBe(true);
+ expect(fixDraftRules).not.toHaveBeenCalled();
+ await act(async () => answer({ count: 1 }));
+ await act(async () => void (await vi.advanceTimersByTimeAsync(0)));
+ });
+
it('asks a page that puts the brand forward for its disclosure, and Add line puts it under the H1 (CE-050)', async () => {
process.env.NEXT_PUBLIC_CONTENT_QUALITY_PHASE = '2';
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
diff --git a/web/src/lib/actions/content-drafts-handoff.test.ts b/web/src/lib/actions/content-drafts-handoff.test.ts
new file mode 100644
index 000000000..45b84e774
--- /dev/null
+++ b/web/src/lib/actions/content-drafts-handoff.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+/** Hand off (CE-051): what the editor sends the API, and why it didn't run. */
+
+const DRAFT = '77777777-7777-7777-7777-777777777777';
+const BRAND = '33333333-3333-3333-3333-333333333333';
+
+vi.mock('@/lib/action-center/assignees', () => ({ readAssignees: vi.fn(async () => new Map()) }));
+vi.mock('@/lib/supabase/admin', () => ({ supabaseAdmin: {} }));
+vi.mock('@/lib/supabase/server', () => ({
+ createClient: vi.fn(async () => ({
+ auth: { getSession: async () => ({ data: { session: { access_token: 't' } } }) },
+ })),
+}));
+
+const { handOffDraft } = await import('./content-drafts');
+
+const answer = (body: unknown, status = 200) => {
+ const fetch = vi.fn(async () => new Response(JSON.stringify(body), { status }));
+ vi.stubGlobal('fetch', fetch);
+ return fetch;
+};
+const request = {
+ items: [{ key: 'readability:longSentences', detail: '2 sentences over 35 words' }],
+ textRules: [],
+ locked: [],
+ origin: 'person' as const,
+};
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('handOffDraft', () => {
+ it('sends the page’s checks to the API’s hand-off, and gives how many it left', async () => {
+ const fetch = answer({ count: 4, batchId: 'b1' });
+ await expect(handOffDraft(DRAFT, BRAND, request)).resolves.toEqual({ count: 4 });
+ const [url, init] = fetch.mock.calls[0] as unknown as [string, RequestInit];
+ expect(url).toMatch(new RegExp(`/api/content-drafts/${DRAFT}/handoff$`));
+ expect(JSON.parse(init.body as string)).toEqual({
+ brandId: BRAND,
+ items: request.items,
+ textRules: [],
+ locked: [],
+ origin: 'person',
+ });
+ });
+
+ it('says why it didn’t run, and an answer lost on the way as unconfirmed', async () => {
+ for (const code of ['not_due', 'already', 'running', 'off', 'open_suggestions', 'ai_budget']) {
+ answer({ code }, 409);
+ await expect(handOffDraft(DRAFT, BRAND, request)).resolves.toEqual({ error: code });
+ }
+ answer({ code: 'something_new' }, 409);
+ await expect(handOffDraft(DRAFT, BRAND, request)).resolves.toEqual({ error: 'failed' });
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => new Response('<html>timeout</html>', { status: 504 })),
+ );
+ await expect(handOffDraft(DRAFT, BRAND, request)).resolves.toEqual({ error: 'unconfirmed' });
+ });
+});
diff --git a/web/src/lib/actions/content-drafts.ts b/web/src/lib/actions/content-drafts.ts
index fa3cd051b..c4837dfc1 100644
--- a/web/src/lib/actions/content-drafts.ts
+++ b/web/src/lib/actions/content-drafts.ts
@@ -2130,6 +2130,8 @@ const AGENT_FIX_ERRORS = [
'published',
/** Start or a rewrite holds the draft (another tab, another member). */
'writing',
+ /** Another fix or hand-off on the draft is under way (another tab, the editor's own). */
+ 'running',
/** Stopped from the editor (CE-027): nothing it wrote is kept. */
'stopped',
'failed',
@@ -2202,6 +2204,77 @@ export async function fixDraftRules(
}
}
+/** Why a hand-off didn't run: Fix's reasons, and an automatic one's (CE-051). */
+const HANDOFF_ERRORS = [
+ ...AGENT_FIX_ERRORS,
+ /** An automatic hand-off on a draft its brand doesn't hand off. */
+ 'not_due',
+ /** The draft had its automatic hand-off. */
+ 'already',
+ /** The API has Quality's phase 2 off (its CONTENT_QUALITY_PHASE is behind the web's). */
+ 'off',
+] as const;
+export type HandOffError = (typeof HANDOFF_ERRORS)[number];
+
+/** What Hand off sends (CE-051): the page's fixable checks, as Fix sends its rules' context. */
+export interface HandOffRequest extends Omit<AgentFixRequest, 'rules'> {
+ /** Each fixable check open on the page, by its suggestion key, with what it names there. */
+ items: { key: string; detail: string }[];
+ /** A person's Hand off, or the editor's on its own (Settings › Content). */
+ origin: 'person' | 'auto';
+}
+
+/**
+ * Hand it off to Content Agent (Quality spec §5, CE-051): the agent fixes
+ * the page's open Quality checks in one run, as suggestions for review,
+ * metered from the organization's AI usage (content-handoff.js). count is
+ * how many it left.
+ */
+export async function handOffDraft(
+ id: string,
+ brandId: string,
+ request: HandOffRequest,
+): Promise<{ count: number } | { error: HandOffError }> {
+ if (!draftId.safeParse(id).success || !draftId.safeParse(brandId).success) {
+ return { error: 'failed' };
+ }
+ const supabase = await createClient();
+ const {
+ data: { session },
+ } = await supabase.auth.getSession();
+ if (!session) return { error: 'failed' };
+ try {
+ const res = await fetch(`${API_BASE_URL}/api/content-drafts/${id}/handoff`, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ Authorization: `Bearer ${session.access_token}`,
+ },
+ body: JSON.stringify({
+ brandId,
+ items: request.items.slice(0, 15).map((item) => ({
+ key: item.key.slice(0, 60),
+ detail: item.detail.slice(0, 500),
+ })),
+ textRules: request.textRules.slice(0, 50).map((text) => text.slice(0, 300)),
+ locked: request.locked.slice(0, 500).map((key) => key.slice(0, 5000)),
+ ...(request.sources ? { sources: request.sources } : {}),
+ origin: request.origin,
+ }),
+ });
+ const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+ if (!res.ok) {
+ if (typeof body.code !== 'string') return { error: 'unconfirmed' };
+ const code = body.code as HandOffError;
+ return { error: (HANDOFF_ERRORS as readonly string[]).includes(code) ? code : 'failed' };
+ }
+ return { count: Number(body.count) || 0 };
+ } catch (err) {
+ console.error('Failed to hand the draft off:', err);
+ return { error: 'unconfirmed' };
+ }
+}
+
const AGENT_WRITE_ERRORS = [
'ai_budget',
'no_subscription',
diff --git a/web/src/lib/content/agent-runs.test.ts b/web/src/lib/content/agent-runs.test.ts
index 57ff034bc..216461485 100644
--- a/web/src/lib/content/agent-runs.test.ts
+++ b/web/src/lib/content/agent-runs.test.ts
@@ -66,3 +66,22 @@ describe('agent runs', () => {
expect(stepMessage({ key: 'write_changes', count: null })).toEqual({ key: 'writeChangesAny' });
});
});
+
+describe('Quality’s hand-off runs (CE-051)', () => {
+ it('reads a hand-off run, its checks read first', () => {
+ const run = agentRunFrom({
+ id: 'run-1',
+ kind: 'handoff',
+ steps: [
+ { key: 'read_checks', count: 6 },
+ { key: 'write_changes', count: null },
+ ],
+ step: 0,
+ started_at: new Date().toISOString(),
+ finished_at: null,
+ outcome: null,
+ });
+ expect(run).toMatchObject({ kind: 'handoff' });
+ expect(stepMessage(run!.steps[0])).toEqual({ key: 'readChecks', count: 6 });
+ });
+});
diff --git a/web/src/lib/content/agent-runs.ts b/web/src/lib/content/agent-runs.ts
index 27b4625c6..f9667a03e 100644
--- a/web/src/lib/content/agent-runs.ts
+++ b/web/src/lib/content/agent-runs.ts
@@ -7,6 +7,8 @@
export const RUN_STEP_KEYS = [
'read_rules',
+ // Quality's hand-off (CE-051): the page's checks instead of its rules.
+ 'read_checks',
'gather_sources',
'write_changes',
'rewrite_page',
@@ -23,7 +25,7 @@ export interface RunStep {
count: number | null;
}
-export type AgentRunKind = 'fix' | 'rewrite' | 'write' | 'brief';
+export type AgentRunKind = 'fix' | 'rewrite' | 'write' | 'brief' | 'handoff';
export interface AgentRun {
id: string;
@@ -59,7 +61,9 @@ export function agentRunFrom(row: Record<string, unknown> | null): AgentRun | nu
: [],
);
const kind = row.kind;
- if (!steps.length || !['fix', 'rewrite', 'write', 'brief'].includes(kind as string)) return null;
+ if (!steps.length || !['fix', 'rewrite', 'write', 'brief', 'handoff'].includes(kind as string)) {
+ return null;
+ }
const outcome = row.outcome;
return {
id: row.id,
diff --git a/web/src/lib/content/hand-off.test.ts b/web/src/lib/content/hand-off.test.ts
new file mode 100644
index 000000000..3df107ace
--- /dev/null
+++ b/web/src/lib/content/hand-off.test.ts
@@ -0,0 +1,84 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { HANDOFF_KEYS, handOffItems } from './hand-off';
+
+/** Hand off (CE-051): what of Quality's suggestions the agent fixes in one run. */
+
+const suggestion = (
+ key: string,
+ over: Partial<{ gain: number; show: string | null; handOff: false }> = {},
+) => ({
+ key,
+ gain: 5,
+ line: `${key} line`,
+ detail: `${key} detail`,
+ show: null as string | null,
+ ...over,
+});
+
+describe('handOffItems', () => {
+ it('sends each fixable suggestion with a gain once, with its line, detail and passage', () => {
+ expect(
+ handOffItems([
+ suggestion('readability:longSentences', { show: 'A very long sentence.' }),
+ suggestion('trust:claimsSourced'),
+ suggestion('readability:longSentences'),
+ // Nothing to gain, or a key it doesn't fix (a to-do's): left out.
+ suggestion('readability:avgSentence', { gain: 0 }),
+ suggestion('eeat:experience'),
+ // One that asks the other way to its check (sentences too short): the person's.
+ suggestion('readability:readingLevel', { handOff: false }),
+ ]),
+ ).toEqual([
+ {
+ key: 'readability:longSentences',
+ detail:
+ 'readability:longSentences line · readability:longSentences detail · Where: "A very long sentence."',
+ },
+ {
+ key: 'trust:claimsSourced',
+ detail: 'trust:claimsSourced line · trust:claimsSourced detail',
+ },
+ ]);
+ });
+
+ it('sends the disclosure only with its line in the page’s language, and keeps each detail short', () => {
+ const disclosure = suggestion('trust:disclosure');
+ expect(handOffItems([disclosure])).toEqual([]);
+ expect(handOffItems([disclosure], { disclosureLine: 'Disclosure: offered by Acme.' })).toEqual([
+ {
+ key: 'trust:disclosure',
+ detail:
+ 'trust:disclosure line · trust:disclosure detail · The line: "Disclosure: offered by Acme."',
+ },
+ ]);
+ const long = suggestion('trust:claimsSourced', { show: 'x'.repeat(900) });
+ const [cut] = handOffItems([long]);
+ expect(cut.detail).toHaveLength(500);
+ expect(cut.detail).toMatch(
+ /^trust:claimsSourced line · trust:claimsSourced detail · Where: "x+…"$/,
+ );
+ });
+
+ it('cuts the passage, never the disclosure line the agent writes as given', () => {
+ const line = `Disclosure: the product this page recommends is offered by ${'Acme '.repeat(30)}.`;
+ const [item] = handOffItems([suggestion('trust:disclosure', { show: 'y'.repeat(400) })], {
+ disclosureLine: line,
+ });
+ expect(item.detail.length).toBeLessThanOrEqual(500);
+ expect(item.detail).toContain(`The line: "${line}"`);
+ expect(item.detail).toMatch(/Where: "y+…"$/);
+ });
+
+ it('knows the checks the API fixes, as the API names them', () => {
+ const server = readFileSync(
+ join(__dirname, '../../../../server/src/lib/content-handoff.js'),
+ 'utf8',
+ );
+ const block = server.slice(server.indexOf('HANDOFF_CHECKS = {'), server.indexOf('};'));
+ const keys = [...block.matchAll(/^\s*'([a-z]+:[A-Za-z]+)':/gm)].map((m) => m[1]);
+ expect(keys).toHaveLength(15);
+ expect([...HANDOFF_KEYS].sort()).toEqual(keys.sort());
+ });
+});
diff --git a/web/src/lib/content/hand-off.ts b/web/src/lib/content/hand-off.ts
new file mode 100644
index 000000000..e43db50d3
--- /dev/null
+++ b/web/src/lib/content/hand-off.ts
@@ -0,0 +1,74 @@
+/**
+ * Hand it off to Content Agent (Quality spec §5, CE-051): what of Quality's
+ * suggestions the agent fixes in one run. Every suggestion is fixable; the
+ * to-dos (what only the person can give: their input, an author, proof, a
+ * placeholder) stay the person's. The server says what each asks
+ * (content-handoff.js, HANDOFF_CHECKS); the editor sends what each names on
+ * the page.
+ */
+
+/** The fixable checks, by Quality's suggestion key, as the API takes them. */
+export const HANDOFF_KEYS: ReadonlySet<string> = new Set([
+ 'readability:avgSentence',
+ 'readability:longSentences',
+ 'readability:readingLevel',
+ 'readability:answerFirst',
+ 'readability:shortParagraphs',
+ 'readability:headingSpacing',
+ 'readability:passiveJargon',
+ 'trust:claimsSourced',
+ 'trust:brandFacts',
+ 'trust:freshSources',
+ 'trust:noWeakSources',
+ 'trust:primarySources',
+ 'trust:disclosure',
+ 'trust:balanced',
+ 'trust:noBrokenLinks',
+]);
+
+/** What the API takes of a check's detail. */
+const MAX_DETAIL = 500;
+
+/**
+ * The checks to hand off: the suggestions with a gain, each once, with its
+ * line, its detail and the passage it shows (cut short to fit, never the
+ * rest). One that asks the other way to its check stays the person's. The
+ * disclosure goes only with the line to add, in the page's language
+ * (disclosureText): the agent writes it as given, never one of its own.
+ */
+export function handOffItems(
+ suggestions: readonly {
+ key: string;
+ gain: number;
+ line: string;
+ detail: string;
+ show: string | null;
+ handOff?: false;
+ }[],
+ { disclosureLine = null }: { disclosureLine?: string | null } = {},
+): { key: string; detail: string }[] {
+ const seen = new Set<string>();
+ return suggestions.flatMap((s) => {
+ if (s.gain <= 0 || s.handOff === false || !HANDOFF_KEYS.has(s.key) || seen.has(s.key)) {
+ return [];
+ }
+ if (s.key === 'trust:disclosure' && !disclosureLine) return [];
+ seen.add(s.key);
+ const head = [
+ s.line,
+ s.detail,
+ s.key === 'trust:disclosure' ? `The line: "${disclosureLine}"` : null,
+ ]
+ .filter(Boolean)
+ .join(' · ');
+ return [{ key: s.key, detail: withPassage(head, s.show) }];
+ });
+}
+
+/** The detail, then the passage it shows as far as the API takes it. */
+function withPassage(head: string, show: string | null): string {
+ const room = MAX_DETAIL - head.length - ' · Where: "…"'.length;
+ if (!show || room < 20) return head.slice(0, MAX_DETAIL);
+ const passage = show.length <= room + 1 ? show : `${show.slice(0, room).trimEnd()}…`;
+ return `${head} · Where: "${passage}"`;
+}