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): rewrite a whole page to its rules as one suggestion (#1393)

Cihan2e9f324f4c48
diff --git a/server/src/lib/content-agent.js b/server/src/lib/content-agent.js
index f2ed8434c..4326073a7 100644
--- a/server/src/lib/content-agent.js
+++ b/server/src/lib/content-agent.js
@@ -481,6 +481,17 @@ export async function hasOpenSuggestions(draftId) {
return (data ?? []).some((row) => row.batch_id === latest && row.status === 'open');
}
+/** A 'writing' this old was left by a server that stopped: it can start again. */
+export const WRITING_STALE_MS = 10 * 60_000;
+
+/** Whether Start or a rewrite holds the draft now (agent_state, 00219). */
+export function agentWriting(draft, now = Date.now()) {
+ return (
+ draft.agent_state === 'writing' &&
+ new Date(draft.agent_state_at).getTime() > now - WRITING_STALE_MS
+ );
+}
+
/**
* Runs the agent on a draft: reads it and its brand, charges the AI usage
* budget, asks the model, and keeps the suggestions the editor can apply as
@@ -492,7 +503,9 @@ export async function hasOpenSuggestions(draftId) {
export async function fixDraftRules({ draftId, brandId, input }) {
const { data: draft, error: draftError } = await supabaseAdmin
.from('content_drafts')
- .select('id, brand_id, title, body_html, page_type, action_id, status, source_url')
+ .select(
+ 'id, brand_id, title, body_html, page_type, action_id, status, source_url, agent_state, agent_state_at',
+ )
.eq('id', draftId)
.maybeSingle();
if (draftError) throw draftError;
@@ -512,6 +525,14 @@ export async function fixDraftRules({ draftId, brandId, input }) {
code: 'open_suggestions',
});
}
+ // Start or a rewrite holds the draft: a batch here would drop its answer,
+ // already charged, when it lands (another tab, another member, the API).
+ if (agentWriting(draft)) {
+ throw Object.assign(new Error('The agent is already writing it'), {
+ status: 409,
+ code: 'writing',
+ });
+ }
const { data: brand, error: brandError } = await supabaseAdmin
.from('brands')
diff --git a/server/src/lib/content-agent.test.js b/server/src/lib/content-agent.test.js
index 955cd4368..270decbb2 100644
--- a/server/src/lib/content-agent.test.js
+++ b/server/src/lib/content-agent.test.js
@@ -679,6 +679,26 @@ describe('fixDraftRules', () => {
expect(generateObject).not.toHaveBeenCalled();
});
+ it('waits while Start or a rewrite holds the draft, which a stopped server no longer does', async () => {
+ rows.content_drafts.agent_state = 'writing';
+ rows.content_drafts.agent_state_at = new Date().toISOString();
+ await expect(
+ fixDraftRules({ draftId: DRAFT, brandId: BRAND, input: input() }),
+ ).rejects.toMatchObject({ status: 409, code: 'writing' });
+ expect(reserveAiBudget).not.toHaveBeenCalled();
+ expect(generateObject).not.toHaveBeenCalled();
+
+ // Left 'writing' long ago: no run holds it.
+ rows.content_drafts.agent_state_at = new Date(Date.now() - 11 * 60_000).toISOString();
+ generateObject.mockResolvedValue({
+ object: { suggestions: [] },
+ usage: { inputTokens: 10, outputTokens: 5 },
+ });
+ await expect(
+ fixDraftRules({ draftId: DRAFT, brandId: BRAND, input: input() }),
+ ).resolves.toEqual({ count: 0, batchId: null });
+ });
+
it('refuses a published draft, or one whose latest batch is still open, before charging', async () => {
rows.content_drafts.status = 'published';
await expect(
diff --git a/server/src/lib/content-rewrite.js b/server/src/lib/content-rewrite.js
new file mode 100644
index 000000000..ceafa0d03
--- /dev/null
+++ b/server/src/lib/content-rewrite.js
@@ -0,0 +1,336 @@
+import { randomBytes } from 'crypto';
+import * as cheerio from 'cheerio';
+import { z } from 'zod';
+import { HEADING_LIMITS, passageKey } from './content-agent.js';
+import { linkKey } from './content-links.js';
+
+/**
+ * Rewrite the page to these rules (Content Editor): the Content Agent
+ * rewrites a whole page in one call, left as ONE suggestion (kind 'page',
+ * 00247) for a person to compare and accept or reject. Small edits stay with
+ * Fix open rules (content-agent.js); this one is for a page far from its
+ * Length, or with many rules open.
+ *
+ * What the page keeps word for word never reaches the model to rewrite:
+ * each passage AI answers quote today (locked), table, image, HTML block,
+ * quote and JSON-LD script goes as a [[KEEP n]] line, described under the
+ * page so the model writes around it, and is put back as it was after the
+ * model answers. A rewrite that drops one is refused.
+ */
+
+/** The most text a page sent whole may hold, its kept blocks left out. */
+export const MAX_REWRITE_CHARS = 60_000;
+
+/** The longest rewritten page kept (00247's check). */
+export const MAX_PAGE_HTML = 500_000;
+
+/** Blocks kept as they are, never rewritten. */
+const KEPT_BLOCKS = new Set(['table', 'img', 'figure', 'blockquote', 'script', 'pre', 'hr']);
+
+/** The tags a rewritten page may hold; anything else is unwrapped to its text. */
+const PAGE_TAGS = new Set([
+ 'h1',
+ 'h2',
+ 'h3',
+ 'p',
+ 'ul',
+ 'ol',
+ 'li',
+ 'strong',
+ 'em',
+ 'b',
+ 'i',
+ 'br',
+ 'a',
+]);
+/** Inline content a line of text at the page's root is wrapped with in a paragraph. */
+const INLINE_TAGS = new Set(['strong', 'em', 'b', 'i', 'br', 'a']);
+
+export const rewriteSchema = z.object({
+ html: z.string().describe('The whole page rewritten, as HTML.'),
+ reason: z.string().describe('One short sentence on what changed.'),
+});
+
+export const REWRITE_SYSTEM_PROMPT = `You are the Content Agent for Answer Engine Optimization (AEO). You rewrite one existing web page, whole, so it meets the rules listed and AI assistants (ChatGPT, Perplexity, Gemini, Copilot, Google's AI Overviews) understand it, trust it and cite it. A person compares your page with theirs and accepts or rejects it.
+
+How to rewrite:
+- Meet every rule listed, and the writer's own rules. Aim at the Length given: the page's whole text, kept blocks included, within 20% of it. When the page is too long, cut repetition, filler and the least useful parts first, and keep its answers, facts and data.
+- Keep the page's facts and voice. Use only facts from the page, the brand and the brief. Never invent numbers, prices, dates, names, customers, sources or quotes; when the page needs a fact you don't have, write a placeholder in square brackets, e.g. [figure, source, year].
+- One H1, the page's title, first. Sections are H2s; questions and sub-sections are H3s.
+- Answer first: under each heading, a short paragraph that answers it, then the detail.
+- Headings are one short line: an H1 up to ${HEADING_LIMITS.h1} characters, others up to ${HEADING_LIMITS.other}. Never put a sentence or an answer in a heading.
+- Each kept line, e.g. <p>[[KEEP 1]]</p>, stands for a block kept word for word: a passage AI assistants quote today, a table, an image, an HTML block or a quote, described under the page. Write it exactly as <p>[[KEEP n]]</p>, on its own, outside lists and paragraphs, once each, where it fits the page; never change, split, merge or drop one, and don't repeat what it says.
+- Keep the page's links on the words they explain. Link only to a URL the page already links to or one listed for you to link to, copied exactly, as <a href="URL">the words</a>. Never invent a URL, and never link a heading.
+- HTML only: h1, h2, h3, p, ul, ol, li, strong, em and a. No Markdown, no code fences, no classes, styles or other tags.
+- "reason" says in one short sentence what you changed, e.g. "cut to about 8,000 characters and answered each heading first".
+- Write in the page's own language.`;
+
+/**
+ * The page's text length as the Rules tab counts it (pageTextLength in
+ * web/src/lib/content/rules.ts): a space between blocks, an entity as one
+ * character, runs of spaces as one.
+ */
+export function textLength(html) {
+ return String(html ?? '')
+ .replace(/<(script|style)\b[\s\S]*?<\/\1>/gi, ' ')
+ .replace(/<\/?(p|h[1-6]|li|td|th|blockquote|br|div)\b[^>]*>/gi, ' ')
+ .replace(/<[^>]*>/g, '')
+ .replace(/&nbsp;/g, ' ')
+ .replace(/&[#a-z0-9]+;/gi, 'x')
+ .replace(/\s+/g, ' ')
+ .trim().length;
+}
+
+const clip = (text, max) => {
+ const one = String(text ?? '')
+ .replace(/\s+/g, ' ')
+ .trim();
+ return one.length > max ? `${one.slice(0, max - 1)}…` : one;
+};
+
+/** What a kept block is, in a few words, for the model to write around it. */
+function describeKept($, $el, tag, quoted) {
+ if (quoted) {
+ const what = /^h[1-6]$/.test(tag) ? `the page's ${tag.toUpperCase()}` : 'a passage';
+ return `${what} AI assistants quote today: "${clip($el.text(), 160)}"`;
+ }
+ if (tag === 'table' || $el.find('table').length) {
+ return `a table, ${$el.find('tr').length} rows: "${clip($el.find('tr').first().text(), 80)}"`;
+ }
+ if (tag === 'img' || $el.find('img').length) {
+ const alt = ($el.is('img') ? $el : $el.find('img').first()).attr('alt');
+ return alt ? `an image: "${clip(alt, 80)}"` : 'an image';
+ }
+ if (tag === 'blockquote') return `a quote: "${clip($el.text(), 120)}"`;
+ if (tag === 'script') return 'structured data (JSON-LD)';
+ if ($el.is('[data-html-block]')) return 'an HTML block';
+ return `a ${tag} block`;
+}
+
+/**
+ * The page as the model gets it: each top-level block kept as it is (a
+ * locked passage, or a table, image, quote, HTML block or script, or a list
+ * holding a locked passage) stands as a <p>[[KEEP n]]</p> line.
+ * - kept: each number's block, as HTML; legend: what each holds;
+ * - h1: the page's own H1 when it isn't kept; h1Token: its number when it is;
+ * - keptChars: the kept blocks' text, which counts toward Length;
+ * - word: the marker's word, KEEP unless the page's own text has it.
+ */
+export function keepBlocks(html, lockedKeys) {
+ const $ = cheerio.load(html || '', null, false);
+ const locked = new Set([...lockedKeys].filter(Boolean));
+ // A page that writes "[[KEEP" itself gets markers of its own.
+ const word = $.root().text().includes('[[KEEP')
+ ? `KEEP_${randomBytes(2).toString('hex')}`
+ : 'KEEP';
+ const kept = new Map();
+ const legend = new Map();
+ const firstH1 = $('h1').first().get(0) ?? null;
+ let h1Token = null;
+ for (const el of $.root().children().get()) {
+ const tag = el.tagName?.toLowerCase();
+ const $el = $(el);
+ const passages = $el.is('h1, h2, h3, h4, h5, h6, p')
+ ? [$el]
+ : $el
+ .find('h1, h2, h3, h4, h5, h6, p')
+ .get()
+ .map((p) => $(p));
+ const quoted = passages.some((p) => locked.has(passageKey(p.text())));
+ const block =
+ KEPT_BLOCKS.has(tag) || $el.is('[data-html-block]') || $el.find('img, table').length > 0;
+ if (!quoted && !block) continue;
+ const n = kept.size + 1;
+ kept.set(n, $.html(el));
+ legend.set(n, describeKept($, $el, tag, quoted));
+ // Only the page's own H1: one inside an HTML block isn't the title.
+ if (firstH1 && (el === firstH1 || $el.find(firstH1).length)) h1Token = n;
+ $el.replaceWith(`<p>[[${word} ${n}]]</p>`);
+ }
+ const keptChars = textLength([...kept.values()].join(' '));
+ return {
+ html: $.html().trim(),
+ kept,
+ legend,
+ word,
+ keptChars,
+ h1Token,
+ h1: firstH1 && h1Token === null ? $.html(firstH1) : null,
+ };
+}
+
+/** The page's own text, its kept lines left out: what there is to rewrite. */
+export function ownText(page) {
+ return textLength(page.html.replace(new RegExp(`\\[\\[${page.word} \\d+\\]\\]`, 'g'), ' '));
+}
+
+/** A page's own link that isn't http(s): a path on its site, an anchor, mail or phone. */
+const LOCAL_HREF = /^(\/(?![/\\])|#|mailto:|tel:)/i;
+
+/** Where a link's address is looked up in the links a rewrite may keep. */
+const hrefKey = (href) => {
+ const raw = String(href ?? '').trim();
+ return linkKey(raw) ?? (LOCAL_HREF.test(raw) ? `local:${raw}` : null);
+};
+
+/**
+ * The links a rewrite may keep, by hrefKey: the brand's pages and the
+ * draft's sources offered to link to (linkAllowList), and every link the
+ * page has, as the page has it (its paths, query and anchor included).
+ */
+export function rewriteLinks(pageHtml, offered) {
+ const links = new Map(offered ?? []);
+ const $ = cheerio.load(pageHtml || '', null, false);
+ $('a[href]').each((_, el) => {
+ const raw = String($(el).attr('href') ?? '').trim();
+ const key = hrefKey(raw);
+ if (key) links.set(key, raw);
+ });
+ return links;
+}
+
+/**
+ * The model's page kept to what the editor takes: the tags above, no
+ * attributes or comments, links only to a URL in `links` (never in a
+ * heading), H4–H6 as H3, code fences gone and text at the page's root put in
+ * paragraphs; one H1, first: a later H1 becomes an H2, and none at all
+ * takes the page's own back. With `h1Kept` the H1 is a kept block, so every
+ * H1 the model wrote becomes an H2.
+ */
+export function cleanPageHtml(html, links, { h1Kept = false, originalH1 = null } = {}) {
+ const unfenced = String(html ?? '')
+ .replace(/^\s*```[a-z]*\s*/i, '')
+ .replace(/\s*```\s*$/, '');
+ const $ = cheerio.load(unfenced, null, false);
+ $('script, style, iframe, object, embed, noscript, template, head, title').remove();
+ $.root()
+ .find('*')
+ .addBack()
+ .contents()
+ .filter((_, node) => node.type === 'comment')
+ .remove();
+ $('h4, h5, h6').each((_, el) => {
+ el.name = 'h3';
+ });
+ $('h1').each((i, el) => {
+ if (h1Kept || i > 0) el.name = 'h2';
+ });
+ for (const el of $('*').get().reverse()) {
+ const tag = el.tagName?.toLowerCase();
+ if (tag === 'a') {
+ const key = hrefKey(el.attribs?.href);
+ const href = key ? links.get(key) : undefined;
+ const inHeading = $(el).parents('h1, h2, h3').length > 0;
+ if (href && !inHeading && $(el).text().trim()) {
+ for (const name of Object.keys(el.attribs ?? {})) $(el).removeAttr(name);
+ $(el).attr('href', href);
+ } else {
+ $(el).replaceWith($(el).contents());
+ }
+ continue;
+ }
+ if (!PAGE_TAGS.has(tag)) {
+ $(el).replaceWith($(el).contents());
+ continue;
+ }
+ for (const name of Object.keys(el.attribs ?? {})) $(el).removeAttr(name);
+ }
+ // Text left at the root (a bare [[KEEP n]], a div unwrapped): one
+ // paragraph a line, inline marks kept with their words.
+ const root = $.root();
+ let run = [];
+ const flush = (before) => {
+ const html = run.map((node) => $.html(node)).join('');
+ for (const node of run) $(node).remove();
+ run = [];
+ const lines = html
+ .split(/\n+/)
+ .map((line) => line.trim())
+ .filter((line) => cheerio.load(line, null, false).root().text().trim());
+ const paragraphs = lines.map((line) => `<p>${line}</p>`).join('');
+ if (!paragraphs) return;
+ if (before) $(before).before(paragraphs);
+ else root.append(paragraphs);
+ };
+ for (const node of root.contents().get()) {
+ if (node.type === 'text' || (node.type === 'tag' && INLINE_TAGS.has(node.name))) {
+ run.push(node);
+ } else if (run.length) {
+ flush(node);
+ }
+ }
+ if (run.length) flush(null);
+ if (!h1Kept && !$('h1').length && originalH1) root.prepend(originalH1);
+ return $.html().trim();
+}
+
+/** Whether the model's answer is a page in HTML, not Markdown or plain text. */
+export function isPageHtml(html) {
+ const text = String(html ?? '');
+ if (/^\s{0,3}#{1,3} \S/m.test(cheerio.load(text, null, false).root().text())) return false;
+ return /<(h[1-3]|p|ul|ol)\b/i.test(text);
+}
+
+/**
+ * The kept blocks put back where the model left their lines, each once,
+ * as they were. Answers the page and the numbers it left out; a number left
+ * inside other text is taken out of it, and counts as left out. With
+ * `h1Token`, the page's kept H1 goes first.
+ */
+export function restoreKept(html, kept, { word = 'KEEP', h1Token = null } = {}) {
+ const $ = cheerio.load(html || '', null, false);
+ const only = new RegExp(`^\\s*\\[\\[${word} (\\d+)\\]\\]\\s*$`);
+ const any = new RegExp(`\\[\\[${word} \\d+\\]\\]`, 'g');
+ const marker = `[[${word} `;
+ const placed = new Set();
+ // The lines, found first: nothing below may touch a kept block.
+ $('p, li, h1, h2, h3').each((_, el) => {
+ const match = $(el).text().match(only);
+ if (!match) return;
+ const n = Number(match[1]);
+ if (!kept.has(n) || placed.has(n)) {
+ $(el).remove();
+ return;
+ }
+ placed.add(n);
+ $(el).attr('data-kept', String(n)).empty();
+ });
+ // Lines run into other text, and the blocks they leave empty.
+ $('*').each((_, el) => {
+ for (const node of el.children ?? []) {
+ if (node.type === 'text' && node.data.includes(marker))
+ node.data = node.data.replace(any, '');
+ }
+ });
+ $('p, li, h1, h2, h3').each((_, el) => {
+ if ($(el).is('[data-kept]') || $(el).find('[data-kept]').length) return;
+ if (!$(el).text().trim() && !$(el).find('img, br').length) $(el).remove();
+ });
+ $('ul, ol').each((_, el) => {
+ if (!$(el).children().length) $(el).remove();
+ });
+ // Then the blocks, as they were; one in a list item goes after its list.
+ $('[data-kept]').each((_, el) => {
+ const n = Number($(el).attr('data-kept'));
+ if (el.tagName === 'li') {
+ const list = $(el).parent();
+ if (list.children().length === 1) list.replaceWith(kept.get(n));
+ else {
+ list.after(kept.get(n));
+ $(el).remove();
+ }
+ return;
+ }
+ $(el).replaceWith(kept.get(n));
+ });
+ if (h1Token !== null && placed.has(h1Token)) {
+ const first = $.root().children().first();
+ const h1 = $.root()
+ .children()
+ .filter((_, el) => $.html(el) === kept.get(h1Token))
+ .first();
+ if (h1.length && first.get(0) !== h1.get(0)) $.root().prepend(h1);
+ }
+ const missing = [...kept.keys()].filter((n) => !placed.has(n));
+ return { html: $.html().trim(), missing };
+}
diff --git a/server/src/lib/content-rewrite.test.js b/server/src/lib/content-rewrite.test.js
new file mode 100644
index 000000000..fe739578c
--- /dev/null
+++ b/server/src/lib/content-rewrite.test.js
@@ -0,0 +1,188 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// content-agent.js reaches the admin client at import time, whose config
+// hard-exits without SUPABASE_* env (as in CI).
+vi.mock('../config/supabase.js', () => ({ default: { from: vi.fn(), rpc: vi.fn() } }));
+const { passageKey } = await import('./content-agent.js');
+const {
+ REWRITE_SYSTEM_PROMPT,
+ cleanPageHtml,
+ isPageHtml,
+ keepBlocks,
+ ownText,
+ restoreKept,
+ rewriteLinks,
+ textLength,
+} = await import('./content-rewrite.js');
+
+/**
+ * Rewrite the page to these rules: what the page keeps word for word goes
+ * to the model as [[KEEP n]] lines and comes back as it was.
+ */
+
+const QUOTED = 'AI assistants quote this sentence about tracking today.';
+const TABLE = '<table><tbody><tr><td><p>Plan</p></td><td><p></p></td></tr></tbody></table>';
+const PAGE =
+ '<h1>Best AEO tools</h1>' +
+ '<p>Ansvisor tracks AI answers across <a href="https://acme.example/engines?ref=aff12#top">six engines</a>.</p>' +
+ `<p>${QUOTED}</p>` +
+ TABLE +
+ '<div data-html-block="PGI+aGk8L2I+"></div>' +
+ '<ul><li><p>See <a href="/pricing">pricing</a>.</p></li></ul>';
+
+const locked = new Set([passageKey(QUOTED)]);
+
+describe('keepBlocks', () => {
+ it('sends a locked passage, a table and an HTML block as kept lines, described', () => {
+ const page = keepBlocks(PAGE, locked);
+ expect(page.html).toContain('<p>[[KEEP 1]]</p><p>[[KEEP 2]]</p><p>[[KEEP 3]]</p>');
+ expect(page.html).not.toContain('quote this sentence');
+ expect(page.kept.get(2)).toBe(TABLE);
+ expect([...page.legend.values()]).toEqual([
+ `a passage AI assistants quote today: "${QUOTED}"`,
+ 'a table, 1 rows: "Plan"',
+ 'an HTML block',
+ ]);
+ // Kept text counts toward Length; the rest is the model's to rewrite, the H1 included.
+ expect(page.keptChars).toBe(textLength(`<p>${QUOTED}</p>${TABLE}`));
+ expect(ownText(page)).toBe(textLength(page.html.replace(/\[\[KEEP \d+\]\]/g, ' ')));
+ expect(page).toMatchObject({ word: 'KEEP', h1Token: null, h1: '<h1>Best AEO tools</h1>' });
+ });
+
+ it('keeps a list whole when it holds a locked passage, and an H1 AI quotes', () => {
+ const page = keepBlocks(
+ `<h1>Best AEO tools</h1><ul><li><p>${QUOTED}</p></li></ul>`,
+ new Set([...locked, passageKey('Best AEO tools')]),
+ );
+ expect(page.html).toBe('<p>[[KEEP 1]]</p><p>[[KEEP 2]]</p>');
+ expect(page.kept.get(2)).toMatch(/^<ul>/);
+ expect(page).toMatchObject({ h1Token: 1, h1: null });
+ expect(page.legend.get(1)).toBe('the page\'s H1 AI assistants quote today: "Best AEO tools"');
+ });
+
+ it('takes no H1 inside an HTML block for the page’s title', () => {
+ const page = keepBlocks(
+ '<h1>Real title</h1><p>Intro.</p><div data-html-block="x"><h1>Widget</h1></div>',
+ new Set(),
+ );
+ expect(page).toMatchObject({ h1Token: null, h1: '<h1>Real title</h1>' });
+ });
+
+ it('marks its lines with a word of its own when the page writes [[KEEP itself', () => {
+ const page = keepBlocks(`<p>Write [[KEEP 1]] to keep.</p>${TABLE}`, new Set());
+ expect(page.word).toMatch(/^KEEP_[0-9a-f]{4}$/);
+ expect(page.html).toContain(`<p>[[${page.word} 1]]</p>`);
+ expect(restoreKept(page.html, page.kept, { word: page.word }).html).toBe(
+ `<p>Write [[KEEP 1]] to keep.</p>${TABLE}`,
+ );
+ });
+});
+
+describe('cleanPageHtml', () => {
+ const links = rewriteLinks(PAGE, new Map([['acme.example/guide', 'https://acme.example/guide']]));
+
+ it('keeps the page’s own links as they are, and the ones offered; unwraps the rest', () => {
+ const html = cleanPageHtml(
+ '<h1>T</h1><p><a href="https://acme.example/engines?ref=aff12#top">six</a> ' +
+ '<a href="/pricing">pricing</a> <a href="https://acme.example/guide/">guide</a> ' +
+ '<a href="https://evil.example">x</a> <a href="javascript:alert(1)">y</a> ' +
+ '<a href="/\\evil.example">z</a></p><h2><a href="/pricing">Pricing</a></h2>',
+ links,
+ );
+ expect(html).toBe(
+ '<h1>T</h1><p><a href="https://acme.example/engines?ref=aff12#top">six</a> ' +
+ '<a href="/pricing">pricing</a> <a href="https://acme.example/guide">guide</a> x y z</p>' +
+ '<h2>Pricing</h2>',
+ );
+ });
+
+ it('keeps one H1, first; takes the page’s back when there is none; an H1 that is kept wins', () => {
+ expect(cleanPageHtml('<h1>A</h1><p>x</p><h1>B</h1><h4>C</h4>', links)).toBe(
+ '<h1>A</h1><p>x</p><h2>B</h2><h3>C</h3>',
+ );
+ expect(cleanPageHtml('<p>x</p>', links, { originalH1: '<h1>Best AEO tools</h1>' })).toBe(
+ '<h1>Best AEO tools</h1><p>x</p>',
+ );
+ expect(cleanPageHtml('<h1>A</h1><p>[[KEEP 1]]</p>', links, { h1Kept: true })).toBe(
+ '<h2>A</h2><p>[[KEEP 1]]</p>',
+ );
+ });
+
+ it('drops what the editor doesn’t take: attributes, scripts, comments, other tags', () => {
+ expect(
+ cleanPageHtml(
+ '<p class="x" style="y" onclick="z()">a <span>b</span></p><script>z()</script><!-- c -->',
+ links,
+ ),
+ ).toBe('<p>a b</p>');
+ });
+
+ it('takes a page out of a code fence, and puts lines left at the root in paragraphs', () => {
+ expect(
+ cleanPageHtml(
+ '```html\n<h1>T</h1>\n[[KEEP 1]]\n<div>Plain <strong>words</strong></div>\n```',
+ links,
+ ),
+ ).toBe('<h1>T</h1><p>[[KEEP 1]]</p><p>Plain <strong>words</strong></p>');
+ });
+});
+
+describe('isPageHtml', () => {
+ it('takes a page in HTML, never one in Markdown or plain text', () => {
+ expect(isPageHtml('<h1>T</h1><p>x</p>')).toBe(true);
+ expect(isPageHtml('# Title\n\n## Section\n\nText')).toBe(false);
+ expect(isPageHtml('Just text.')).toBe(false);
+ });
+});
+
+describe('restoreKept', () => {
+ it('puts each kept block back where its line is, once, as it was', () => {
+ const page = keepBlocks(PAGE, locked);
+ const { html, missing } = restoreKept(
+ '<h1>Best AEO tools</h1><p>[[KEEP 2]]</p><p>Short intro.</p><p>[[KEEP 1]]</p>' +
+ '<p>[[KEEP 3]]</p><p>[[KEEP 1]]</p>',
+ page.kept,
+ );
+ expect(missing).toEqual([]);
+ // The table's empty cell stays as the editor wrote it.
+ expect(html).toBe(
+ `<h1>Best AEO tools</h1>${TABLE}<p>Short intro.</p><p>${QUOTED}</p>${page.kept.get(3)}`,
+ );
+ });
+
+ it('says which it left out, and takes a line run into other text out of it', () => {
+ const page = keepBlocks(PAGE, locked);
+ const { html, missing } = restoreKept(
+ '<p>Intro [[KEEP 1]] more.</p><ul><li>[[KEEP 2]]</li><li>Point</li></ul>',
+ page.kept,
+ );
+ expect(missing).toEqual([1, 3]);
+ // A block in a list item goes after its list.
+ expect(html).toBe(`<p>Intro more.</p><ul><li>Point</li></ul>${TABLE}`);
+ });
+
+ it('puts the page’s kept H1 first', () => {
+ const page = keepBlocks(
+ '<h1>Best AEO tools</h1><p>Intro.</p>',
+ new Set([passageKey('Best AEO tools')]),
+ );
+ const { html } = restoreKept('<p>New intro.</p><p>[[KEEP 1]]</p>', page.kept, {
+ h1Token: page.h1Token,
+ });
+ expect(html).toBe('<h1>Best AEO tools</h1><p>New intro.</p>');
+ });
+});
+
+describe('the rewrite', () => {
+ it('counts the page’s text as the Rules tab does, not its markup', () => {
+ // A space between blocks, an entity as one character.
+ expect(textLength('<h1>Ab</h1><p>c d &amp; e</p>')).toBe('Ab c d x e'.length);
+ });
+
+ it('tells the model to keep every kept line, the facts and one H1, in HTML', () => {
+ expect(REWRITE_SYSTEM_PROMPT).toContain('never change, split, merge or drop one');
+ expect(REWRITE_SYSTEM_PROMPT).toContain('Never invent numbers');
+ expect(REWRITE_SYSTEM_PROMPT).toContain('One H1, the page');
+ expect(REWRITE_SYSTEM_PROMPT).toContain('No Markdown, no code fences');
+ });
+});
diff --git a/server/src/lib/content-writer.js b/server/src/lib/content-writer.js
index cab74f636..168022230 100644
--- a/server/src/lib/content-writer.js
+++ b/server/src/lib/content-writer.js
@@ -14,10 +14,24 @@ import {
passageKey,
promptPassages,
suggestionsSchema,
+ WRITING_STALE_MS,
} from './content-agent.js';
import { contentBriefModelId, rebuildSources } from './content-brief.js';
import { linkAllowList, linkTargetsPrompt, readLinkTargets } from './content-links.js';
import { pageTypeFormat } from './content-page-types.js';
+import {
+ MAX_PAGE_HTML,
+ MAX_REWRITE_CHARS,
+ REWRITE_SYSTEM_PROMPT,
+ cleanPageHtml,
+ isPageHtml,
+ keepBlocks,
+ ownText,
+ restoreKept,
+ rewriteLinks,
+ rewriteSchema,
+ textLength,
+} from './content-rewrite.js';
import { getLanguageName } from './languages.js';
import { logger } from './logger.js';
import { reserveAiBudget } from './plan-guard.js';
@@ -41,8 +55,9 @@ import { reserveAiBudget } from './plan-guard.js';
/** How long the model may take: nobody waits on the request. */
const CALL_TIMEOUT_MS = 180_000;
-/** A 'writing' this old was left by a server that stopped: it can start again. */
-export const WRITING_STALE_MS = 10 * 60_000;
+// A 'writing' older than WRITING_STALE_MS (content-agent.js, which Fix open
+// rules checks too) was left by a server that stopped: it can start again.
+export { WRITING_STALE_MS };
/**
* The drafts the agent writes in: still being worked on, a draft or one in
@@ -177,7 +192,10 @@ Call to action: ${opportunityBrief.callToAction || '—'}`;
return 'No brief: plan the sections from the questions and AI searches below.';
}
-/** What the model is told, for a new page or an existing one. */
+/**
+ * What the model is told, for a new page, an existing one (passage by
+ * passage) or one it rewrites whole (`current`: keepBlocks' page).
+ */
export function buildWritePrompt({
brand,
draft,
@@ -188,20 +206,23 @@ export function buildWritePrompt({
more = false,
lockedKeys,
linkTargets = '',
+ current = null,
}) {
const { sources } = input;
const rules = input.rules.map((r) => `${r.key}: ${r.name}${r.detail ? ` — ${r.detail}` : ''}`);
const own = input.textRules.map((text) => `- ${text}`);
- const page = passages
- ? `The page, passage by passage:\n${passages
- .map((p, i) => {
- const locked = lockedKeys.has(passageKey(p.text)) ? ', LOCKED' : '';
- return `[${i + 1}] (${p.tag}${locked}) ${p.text}`;
- })
- .join(
- '\n',
- )}${more ? '\n(The page goes on; suggest changes only to the passages above.)' : ''}`
- : `Write a new page titled about: ${draft.title || 'the questions below'}.`;
+ const page = current
+ ? rewritePagePrompt(current)
+ : passages
+ ? `The page, passage by passage:\n${passages
+ .map((p, i) => {
+ const locked = lockedKeys.has(passageKey(p.text)) ? ', LOCKED' : '';
+ return `[${i + 1}] (${p.tag}${locked}) ${p.text}`;
+ })
+ .join(
+ '\n',
+ )}${more ? '\n(The page goes on; suggest changes only to the passages above.)' : ''}`
+ : `Write a new page titled about: ${draft.title || 'the questions below'}.`;
return `Brand: ${brand?.name || 'Unknown'}
Industry: ${brand?.industry || 'Not specified'}
Description: ${brand?.description || 'N/A'}
@@ -229,7 +250,20 @@ ${list(rules)}
${own.length ? `\nThe writer's own rules:\n${own.join('\n')}\n` : ''}${linkTargets ? `\n${linkTargets}\n` : ''}
${page}
-Write in ${getLanguageName(brand?.language)}.`;
+Write in ${current ? "the page's own language" : getLanguageName(brand?.language)}.`;
+}
+
+/** The page a rewrite starts from: its HTML with kept lines, and what each holds. */
+function rewritePagePrompt(current) {
+ const total = ownText(current) + current.keptChars;
+ const legend = [...current.legend].map(([n, what]) => `- [[${current.word} ${n}]]: ${what}`);
+ const h1 =
+ current.h1Token !== null
+ ? `The page's H1 is [[${current.word} ${current.h1Token}]]: keep it first, and write no other H1.\n`
+ : '';
+ return `The page now, as HTML: about ${total} characters of text, ${current.keptChars} of them in its kept blocks, which count toward Length.
+${current.html}
+${legend.length ? `\nWhat each kept line holds (kept as it is):\n${legend.join('\n')}\n` : ''}${h1}`;
}
/**
@@ -258,7 +292,7 @@ async function organizationWriting(organizationId, draftId, staleBefore) {
* once the budget is spent, and the provider's error when the model isn't
* set up — all before anything runs.
*/
-export async function startDraftWriting({ draftId, brandId, input }) {
+export async function startDraftWriting({ draftId, brandId, input, rewrite = false }) {
const { data: draft, error: draftError } = await supabaseAdmin
.from('content_drafts')
.select(
@@ -286,14 +320,38 @@ export async function startDraftWriting({ draftId, brandId, input }) {
code: 'writing',
});
}
- // An existing page's run leaves a new batch, which would hide the open
- // one (the editor shows the latest), as Fix open rules and the API refuse.
- if (draft.method === 'optimize' && (await hasOpenSuggestions(draftId))) {
+ // An existing page's run, and a rewrite, leave a new batch, which would
+ // hide the open one (the editor shows the latest), as Fix open rules and
+ // the API refuse.
+ if ((rewrite || draft.method === 'optimize') && (await hasOpenSuggestions(draftId))) {
throw Object.assign(new Error('Decide the open suggestions first'), {
status: 409,
code: 'open_suggestions',
});
}
+ if (rewrite) {
+ // A page to rewrite, small enough to send whole.
+ if (!draftPassages(draft.body_html).length) {
+ throw Object.assign(new Error('The page has no text to rewrite'), {
+ status: 422,
+ code: 'empty',
+ });
+ }
+ const page = keepBlocks(draft.body_html, new Set(input.locked.map(passageKey)));
+ // Kept blocks aren't rewritten: a page that is only those has nothing to rewrite.
+ if (!ownText(page)) {
+ throw Object.assign(new Error('The page has no text to rewrite'), {
+ status: 422,
+ code: 'empty',
+ });
+ }
+ if (ownText(page) > MAX_REWRITE_CHARS) {
+ throw Object.assign(new Error('The page is too long to rewrite whole'), {
+ status: 422,
+ code: 'too_long',
+ });
+ }
+ }
const { data: brand, error: brandError } = await supabaseAdmin
.from('brands')
@@ -321,7 +379,12 @@ export async function startDraftWriting({ draftId, brandId, input }) {
// Claimed once: a second start meanwhile finds it writing.
const { data: claimed, error: claimError } = await supabaseAdmin
.from('content_drafts')
- .update({ agent_state: 'writing', agent_state_at: new Date().toISOString() })
+ .update({
+ agent_state: 'writing',
+ agent_state_at: new Date().toISOString(),
+ // Which run, for every device: a failed rewrite is tried again as one.
+ agent_run: rewrite ? 'rewrite' : 'write',
+ })
.eq('id', draftId)
.in('status', OPEN_STATUSES)
.or(`agent_state.is.null,agent_state.eq.failed,agent_state_at.lt."${staleBefore}"`)
@@ -335,7 +398,7 @@ export async function startDraftWriting({ draftId, brandId, input }) {
});
}
- runDraftWriting({ draft, brand, model, input, budget }).catch((err) =>
+ runDraftWriting({ draft, brand, model, input, budget, rewrite }).catch((err) =>
logger.error({ err, draftId }, '[content-writer] run failed'),
);
} catch (err) {
@@ -370,13 +433,98 @@ async function letGo(draftId) {
return { skipped: true };
}
+/**
+ * A whole page rewritten to the rules, left as ONE suggestion (kind 'page',
+ * 00247) beside the page as it was: the person compares them and accepts or
+ * rejects it. What the page keeps word for word goes as [[KEEP n]] lines and
+ * is put back as it was (content-rewrite.js); a rewrite that drops one, or
+ * leaves no page, fails the run. The draft's status doesn't change.
+ */
+async function rewritePage({ draft, brand, model, input, budget, prompts, brief }) {
+ const page = keepBlocks(draft.body_html, new Set(input.locked.map(passageKey)));
+ const ruleKeys = new Set(input.rules.map((r) => r.key));
+ // The Length rule's target; with Length off, the page keeps its length.
+ const length = ruleKeys.has('length') ? input.sources.length : textLength(draft.body_html);
+ // Where it may link: the brand's pages and the draft's sources (A).
+ const targets = await readLinkTargets({
+ brandId: draft.brand_id,
+ draftId: draft.id,
+ sourceUrl: draft.source_url,
+ ruleKeys,
+ });
+ const { object, usage } = await generateObject({
+ model,
+ schema: rewriteSchema,
+ system: REWRITE_SYSTEM_PROMPT,
+ prompt: buildWritePrompt({
+ brand,
+ draft,
+ prompts,
+ brief,
+ input: { ...input, sources: { ...input.sources, length } },
+ linkTargets: linkTargetsPrompt(targets, ruleKeys),
+ current: page,
+ }),
+ abortSignal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+ });
+ await budget.charge(usage);
+
+ if (!isPageHtml(object.html)) throw new Error('The agent answered with no page in HTML');
+ const cleaned = cleanPageHtml(
+ object.html,
+ rewriteLinks(draft.body_html, linkAllowList(targets)),
+ { h1Kept: page.h1Token !== null, originalH1: page.h1 },
+ );
+ const { html, missing } = restoreKept(cleaned, page.kept, {
+ word: page.word,
+ h1Token: page.h1Token,
+ });
+ if (missing.length) {
+ throw new Error(`The rewrite left out ${missing.length} kept block(s)`);
+ }
+ if (!textLength(html)) throw new Error('The agent left no page to review');
+ if (html.length > MAX_PAGE_HTML) throw new Error('The rewritten page is too long to keep');
+ // A batch that landed during the run stays the one to decide.
+ if (await hasOpenSuggestions(draft.id)) {
+ logger.info({ draftId: draft.id }, '[content-writer] open suggestions came in during the run');
+ return await letGo(draft.id);
+ }
+ const batchId = randomUUID();
+ const { error: insertError } = await supabaseAdmin.from('content_draft_suggestions').insert({
+ draft_id: draft.id,
+ batch_id: batchId,
+ action_id: draft.action_id ?? null,
+ position: 0,
+ kind: 'page',
+ // The passage it stands at: the page's first.
+ block_text:
+ clean(draftPassages(draft.body_html)[0]?.text).slice(0, 5000) || clean(draft.title) || 'Page',
+ before_text: '',
+ before_html: draft.body_html,
+ after_text: html,
+ reason: clean(object.reason).slice(0, 300) || 'Rewrote the page to the rules',
+ rule_keys: [...ruleKeys],
+ });
+ if (insertError) throw insertError;
+ if (!(await finish(draft.id, { agent_state: null }, { openOnly: true }))) {
+ // Nobody reviews a rewrite of a page already marked ready.
+ const { error: dropError } = await supabaseAdmin
+ .from('content_draft_suggestions')
+ .delete()
+ .eq('batch_id', batchId);
+ if (dropError) throw dropError;
+ return await letGo(draft.id);
+ }
+ return { rewritten: true };
+}
+
/**
* The run itself: the page written, or the suggestions left, and the draft
* In review; 'failed' when the model fails or leaves nothing to review. The
* model's answer is charged to the hold Start took on the budget
* (reserveAiBudget); a run that ends before one lets the hold go.
*/
-export async function runDraftWriting({ draft, brand, model, input, budget }) {
+export async function runDraftWriting({ draft, brand, model, input, budget, rewrite = false }) {
try {
const [promptsRes, opportunityRes] = await Promise.all([
input.sources.promptIds.length
@@ -401,6 +549,10 @@ export async function runDraftWriting({ draft, brand, model, input, budget }) {
const prompts = (promptsRes.data ?? []).map((p) => p.text);
const brief = briefText(draft.brief, opportunityRes.data?.brief);
+ if (rewrite) {
+ return await rewritePage({ draft, brand, model, input, budget, prompts, brief });
+ }
+
if (draft.method === 'create') {
const { object, usage } = await generateObject({
model,
diff --git a/server/src/lib/content-writer.test.js b/server/src/lib/content-writer.test.js
index bbdc33009..b75fcc92a 100644
--- a/server/src/lib/content-writer.test.js
+++ b/server/src/lib/content-writer.test.js
@@ -85,6 +85,7 @@ vi.mock('./content-agent.js', async (importOriginal) => ({
const { briefText, renderPage, runDraftWriting, startDraftWriting } =
await import('./content-writer.js');
+const { textLength } = await import('./content-rewrite.js');
const { passageKey } = await import('./content-agent.js');
const { PlanLimitError } = await import('./plan-guard.js');
// The real hold: self-hosted here, so it reserves nothing and writes each charge.
@@ -207,7 +208,8 @@ describe('startDraftWriting', () => {
'org-1',
expect.objectContaining({ feature: 'content', modelId: expect.any(String) }),
);
- expect(draftUpdates()[0]).toMatchObject({ agent_state: 'writing' });
+ // Which run holds it, for every device (00247).
+ expect(draftUpdates()[0]).toMatchObject({ agent_state: 'writing', agent_run: 'write' });
await vi.waitFor(() => expect(draftUpdates()).toHaveLength(2));
expect(draftUpdates()[1]).toMatchObject({
@@ -507,3 +509,157 @@ describe('runDraftWriting on an existing page', () => {
expect(draftUpdates()).toEqual([{ agent_state: 'failed', agent_state_at: expect.any(String) }]);
});
});
+
+describe('Rewrite the page to these rules', () => {
+ const QUOTED = 'Pour-over coffee tastes cleaner than a French press.';
+ const existing = draftRow({
+ method: 'optimize',
+ status: 'in_review',
+ body_html:
+ `<h1>Pour-over</h1><p>${QUOTED}</p><p>Use good coffee. ${'Filler. '.repeat(20)}</p>` +
+ '<table><tbody><tr><td>Ratio</td><td>1:16</td></tr></tbody></table>' +
+ '<p>See <a href="/pricing">pricing</a>.</p>',
+ action_id: 'act-1',
+ });
+ const locked = [passageKey(QUOTED)];
+ const run = (over = {}) =>
+ runDraftWriting({
+ draft: existing,
+ brand,
+ model: 'model:m',
+ input: input({ locked, ...over }),
+ budget,
+ rewrite: true,
+ });
+ const answer = (html, reason = 'cut to about 3,000 characters') =>
+ generateObject.mockResolvedValue({
+ object: { html, reason },
+ usage: { inputTokens: 900, outputTokens: 700 },
+ });
+
+ it('starts only on a page with text, small enough to send whole, and no open batch', async () => {
+ rows.content_drafts = existing;
+ hasOpenSuggestions.mockResolvedValueOnce(true);
+ await expect(
+ startDraftWriting({ draftId: DRAFT, brandId: BRAND, input: input(), rewrite: true }),
+ ).rejects.toMatchObject({ status: 409, code: 'open_suggestions' });
+ rows.content_drafts = { ...existing, method: 'create', body_html: '<p> </p>' };
+ await expect(
+ startDraftWriting({ draftId: DRAFT, brandId: BRAND, input: input(), rewrite: true }),
+ ).rejects.toMatchObject({ status: 422, code: 'empty' });
+ rows.content_drafts = { ...existing, body_html: `<p>${'word '.repeat(13_000)}</p>` };
+ await expect(
+ startDraftWriting({ draftId: DRAFT, brandId: BRAND, input: input(), rewrite: true }),
+ ).rejects.toMatchObject({ status: 422, code: 'too_long' });
+ // Refused before anything was held or claimed.
+ expect(reserveAiBudget).not.toHaveBeenCalled();
+ expect(draftUpdates()).toEqual([]);
+ });
+
+ it('claims the draft as a rewrite, so every device tries a failed one again as one', async () => {
+ rows.content_drafts = existing;
+ answer('<h1>Pour-over</h1><p>[[KEEP 1]]</p><p>[[KEEP 2]]</p><p>Shorter.</p>');
+ await expect(
+ startDraftWriting({
+ draftId: DRAFT,
+ brandId: BRAND,
+ input: input({ locked }),
+ rewrite: true,
+ }),
+ ).resolves.toEqual({ started: true });
+ expect(draftUpdates()[0]).toMatchObject({ agent_state: 'writing', agent_run: 'rewrite' });
+ await vi.waitFor(() => expect(draftUpdates().length).toBeGreaterThan(1));
+ });
+
+ it('leaves the whole page as one suggestion, with what it kept put back as it was', async () => {
+ answer(
+ '<h1>Pour-over coffee</h1><p>[[KEEP 1]]</p><p>Use good coffee, freshly ground.</p>' +
+ '<p>[[KEEP 2]]</p><p>See <a href="/pricing">pricing</a> or <a href="https://evil.example">this</a>.</p>',
+ );
+ await expect(
+ run({
+ rules: [
+ { key: 'length', name: 'Length', detail: 'aim: 3,000 characters' },
+ { key: 'faq', name: 'FAQ with 5 questions', detail: 'aim: 5' },
+ ],
+ }),
+ ).resolves.toEqual({ rewritten: true });
+
+ const { system, prompt } = generateObject.mock.calls[0][0];
+ expect(system).toContain('stands for a block kept word for word');
+ // The quoted passage and the table never reach the model to rewrite:
+ // they are described, and count toward Length.
+ expect(prompt).toContain('Length: about 3000 characters.');
+ expect(prompt).toMatch(
+ /The page now, as HTML: about \d+ characters of text, \d+ of them in its kept blocks/,
+ );
+ expect(prompt).toContain(`- [[KEEP 1]]: a passage AI assistants quote today: "${QUOTED}"`);
+ expect(prompt).toContain('- [[KEEP 2]]: a table, 1 rows: "Ratio1:16"');
+ expect(prompt).not.toContain(`<p>${QUOTED}</p>`);
+ expect(prompt).toContain("Write in the page's own language.");
+ expect(budget.charge).toHaveBeenCalledWith({ inputTokens: 900, outputTokens: 700 });
+
+ const row = writes.find((w) => w.table === 'content_draft_suggestions').value;
+ expect(row).toMatchObject({
+ draft_id: DRAFT,
+ action_id: 'act-1',
+ position: 0,
+ kind: 'page',
+ block_text: 'Pour-over',
+ before_text: '',
+ before_html: existing.body_html,
+ reason: 'cut to about 3,000 characters',
+ rule_keys: ['length', 'faq'],
+ });
+ expect(row.after_text).toBe(
+ `<h1>Pour-over coffee</h1><p>${QUOTED}</p><p>Use good coffee, freshly ground.</p>` +
+ '<table><tbody><tr><td>Ratio</td><td>1:16</td></tr></tbody></table>' +
+ '<p>See <a href="/pricing">pricing</a> or this.</p>',
+ );
+ // The agent lets go; the draft's status stays as it was.
+ expect(draftUpdates().at(-1)).toEqual({
+ agent_state: null,
+ agent_state_at: expect.any(String),
+ });
+ });
+
+ it('keeps the page’s length when the Length rule is off', async () => {
+ answer('<h1>Pour-over</h1><p>[[KEEP 1]]</p><p>[[KEEP 2]]</p><p>Shorter.</p>');
+ await run({ rules: [{ key: 'faq', name: 'FAQ', detail: '' }] });
+ const { prompt } = generateObject.mock.calls[0][0];
+ expect(prompt).toContain(`Length: about ${textLength(existing.body_html)} characters.`);
+ });
+
+ it('fails the run on an answer that isn’t a page in HTML', async () => {
+ answer('# Pour-over\n\n[[KEEP 1]]\n\n[[KEEP 2]]');
+ await expect(run()).resolves.toEqual({ failed: true });
+ expect(writes.find((w) => w.table === 'content_draft_suggestions')).toBeUndefined();
+ });
+
+ it('drops the rewrite of a page marked ready during the run', async () => {
+ answer('<h1>Pour-over</h1><p>[[KEEP 1]]</p><p>[[KEEP 2]]</p><p>Shorter.</p>');
+ finished = null;
+ await expect(run()).resolves.toEqual({ skipped: true });
+ const insert = writes.find(
+ (w) => w.table === 'content_draft_suggestions' && w.kind === 'insert',
+ );
+ const drop = writes.find((w) => w.table === 'content_draft_suggestions' && w.kind === 'delete');
+ expect(drop.filters).toContainEqual(['batch_id', insert.value.batch_id]);
+ });
+
+ it('fails the run when the rewrite drops what it had to keep', async () => {
+ answer('<h1>Pour-over</h1><p>[[KEEP 2]]</p><p>A new page without the quoted passage.</p>');
+ await expect(run()).resolves.toEqual({ failed: true });
+ expect(writes.find((w) => w.table === 'content_draft_suggestions')).toBeUndefined();
+ expect(draftUpdates()).toEqual([{ agent_state: 'failed', agent_state_at: expect.any(String) }]);
+ // The answer was still paid for.
+ expect(budget.charge).toHaveBeenCalledTimes(1);
+ });
+
+ it('adds nothing over a batch that came in during the run', async () => {
+ answer('<h1>Pour-over</h1><p>[[KEEP 1]]</p><p>[[KEEP 2]]</p><p>Shorter.</p>');
+ hasOpenSuggestions.mockResolvedValue(true);
+ await expect(run()).resolves.toEqual({ skipped: true });
+ expect(writes.find((w) => w.table === 'content_draft_suggestions')).toBeUndefined();
+ });
+});
diff --git a/server/src/routes/content-drafts.js b/server/src/routes/content-drafts.js
index 4a6cf5d8e..2a00d0dde 100644
--- a/server/src/routes/content-drafts.js
+++ b/server/src/routes/content-drafts.js
@@ -129,4 +129,45 @@ router.post('/:draftId/write', async (req, res) => {
}
});
+/**
+ * POST /api/content-drafts/:draftId/rewrite
+ * Body: as /write ({ brandId, sources, rules, textRules, locked }).
+ * Rewrite the page to these rules: the agent rewrites the whole page in the
+ * background and leaves it as ONE suggestion to compare and accept or
+ * reject. Answers 202 { started: true } at once; 409 as /write (not_draft,
+ * writing, org_writing, open_suggestions); 422 when the page has no text
+ * (empty) or is too long to send whole (too_long).
+ */
+router.post('/:draftId/rewrite', async (req, res) => {
+ const draftId = z.guid().safeParse(req.params.draftId);
+ const parsed = writeBody.safeParse(req.body ?? {});
+ if (!draftId.success || !parsed.success) {
+ return res.status(400).json({ error: 'Invalid request', code: 'invalid' });
+ }
+ const { brandId, ...input } = parsed.data;
+ try {
+ await assertBrandAccess(brandId, req.user.id);
+ const result = await startDraftWriting({
+ draftId: draftId.data,
+ brandId,
+ input,
+ rewrite: true,
+ });
+ return res.status(202).json(result);
+ } catch (err) {
+ if (err instanceof PlanLimitError) {
+ // 402: no active subscription, not a spent budget.
+ const code = err.statusCode === 402 ? 'no_subscription' : 'ai_budget';
+ return res.status(err.statusCode).json({ error: err.message, code });
+ }
+ if (ERROR_CODES[err?.status]) {
+ return res
+ .status(err.status)
+ .json({ error: err.message, code: err.code ?? ERROR_CODES[err.status] });
+ }
+ req.log.error({ err }, 'content draft agent rewrite error');
+ return res.status(502).json({ error: 'The agent could not start', code: 'failed' });
+ }
+});
+
export default router;
diff --git a/server/src/routes/content-drafts.test.js b/server/src/routes/content-drafts.test.js
index a4dcec371..55604a82b 100644
--- a/server/src/routes/content-drafts.test.js
+++ b/server/src/routes/content-drafts.test.js
@@ -5,6 +5,7 @@ import express from 'express';
* POST /api/content-drafts/:draftId/brief (CE-007): Rebuild outline;
* POST /api/content-drafts/:draftId/suggestions (CE-018): Fix open rules with agent; and
* POST /api/content-drafts/:draftId/write (CE-015): Start's Agent.
+ * POST /api/content-drafts/:draftId/rewrite: Rewrite the page to these rules.
*/
const BRAND = '33333333-3333-3333-3333-333333333333';
@@ -170,6 +171,35 @@ describe('POST /api/content-drafts/:draftId/write', () => {
});
});
+describe('POST /api/content-drafts/:draftId/rewrite', () => {
+ const rewrite = (body) =>
+ fetch(`${baseUrl}/${DRAFT}/rewrite`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(body),
+ });
+
+ it('starts a whole-page rewrite and answers at once', async () => {
+ const res = await rewrite({ brandId: BRAND, sources, locked: ['quoted words'] });
+ expect(res.status).toBe(202);
+ expect(startDraftWriting).toHaveBeenCalledWith({
+ draftId: DRAFT,
+ brandId: BRAND,
+ input: { sources, rules: [], textRules: [], locked: ['quoted words'] },
+ rewrite: true,
+ });
+ });
+
+ it('says why it didn’t start', async () => {
+ startDraftWriting.mockRejectedValueOnce(
+ Object.assign(new Error('too long'), { status: 422, code: 'too_long' }),
+ );
+ const res = await rewrite({ brandId: BRAND, sources });
+ expect(res.status).toBe(422);
+ await expect(res.json()).resolves.toMatchObject({ code: 'too_long' });
+ });
+});
+
const fix = (body) =>
fetch(`${baseUrl}/${DRAFT}/suggestions`, {
method: 'POST',
diff --git a/supabase/migrations/00247_content_page_suggestions.sql b/supabase/migrations/00247_content_page_suggestions.sql
new file mode 100644
index 000000000..c439f4ff3
--- /dev/null
+++ b/supabase/migrations/00247_content_page_suggestions.sql
@@ -0,0 +1,110 @@
+-- ============================================================================
+-- 00247: a whole-page suggestion (Content Editor, Rewrite the page to these rules)
+-- ============================================================================
+-- Apply rules with Agent leaves at most 8 small edits a run, which can't
+-- bring a 19,000-character page to an 8,000-character Length (about 2% a
+-- run on prod, 2026-10-23). Rewrite the page to these rules has the Content
+-- Agent rewrite the whole page in one call, left as ONE suggestion the
+-- person compares with their page and accepts or rejects:
+--
+-- * kind 'page': after_text is the whole page's HTML, up to 500,000
+-- characters (the editor's body limit), not 20,000;
+-- * before_html: the page as the agent read it, which the editor checks
+-- the page against before applying it and puts back on Undo. A page
+-- suggestion has it; the others don't;
+-- * before_text stays '' for it, as for an insert.
+--
+-- Rows are still written by the server only; the decide RPC (00217) and
+-- RLS are unchanged.
+--
+-- content_drafts.agent_run says which run holds the draft ('write' or
+-- 'rewrite'), so every device knows a failed rewrite from a failed Start;
+-- 00219's guard keeps it server-set.
+
+alter table public.content_draft_suggestions
+ add column if not exists before_html text;
+
+alter table public.content_draft_suggestions
+ drop constraint if exists content_draft_suggestions_kind_check,
+ add constraint content_draft_suggestions_kind_check
+ check (kind in ('replace', 'insert', 'page'));
+
+alter table public.content_draft_suggestions
+ drop constraint if exists content_draft_suggestions_after_text_check,
+ add constraint content_draft_suggestions_after_text_check
+ check (char_length(after_text) between 1 and case when kind = 'page' then 500000 else 20000 end);
+
+alter table public.content_draft_suggestions
+ drop constraint if exists content_draft_suggestions_check,
+ add constraint content_draft_suggestions_check
+ check (kind in ('insert', 'page') or before_text <> '');
+
+alter table public.content_draft_suggestions
+ drop constraint if exists content_draft_suggestions_before_html_check,
+ add constraint content_draft_suggestions_before_html_check
+ check ((kind = 'page') = (before_html is not null)
+ and char_length(coalesce(before_html, '')) <= 500000);
+
+comment on column public.content_draft_suggestions.before_html is
+ 'A page suggestion''s page as the agent read it (kind ''page'', 00247): checked against the editor''s page before applying, and put back on Undo. Null for the others.';
+
+-- Which run holds the draft, or last held it (agent_state): Start with Agent
+-- ('write': a new page, or suggestions on a live one) or Rewrite the page to
+-- these rules ('rewrite'). The editor reads it to say which run failed and to
+-- try that one again, on any device: a failed rewrite tried again is a
+-- rewrite to compare, never a new page over the current one. Server-set,
+-- with agent_state.
+alter table public.content_drafts
+ add column if not exists agent_run text;
+
+alter table public.content_drafts
+ drop constraint if exists content_drafts_agent_run_check,
+ add constraint content_drafts_agent_run_check
+ check (agent_run is null or agent_run in ('write', 'rewrite'));
+
+comment on column public.content_drafts.agent_run is
+ 'Content Editor: the run that holds the draft or last held it (00247): ''write'' (Start with Agent) or ''rewrite'' (Rewrite the page to these rules). Server-set, with agent_state.';
+
+-- 00219's guard, with agent_run among the columns only the server sets.
+create or replace function public.guard_content_draft_server_columns()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+begin
+ -- A role that bypasses RLS is server-side (service role, migrations).
+ if (select rolbypassrls from pg_catalog.pg_roles where rolname = current_user) then
+ return new;
+ end if;
+
+ if tg_op = 'INSERT' then
+ if new.score_before is not null or new.score_after is not null then
+ raise exception 'content draft scores are set server-side'
+ using errcode = '42501';
+ end if;
+ if new.action_id is not null then
+ raise exception 'content draft action is set server-side'
+ using errcode = '42501';
+ end if;
+ if new.agent_state is not null or new.agent_state_at is not null
+ or new.agent_run is not null then
+ raise exception 'content draft agent state is set server-side'
+ using errcode = '42501';
+ end if;
+ elsif new.brand_id is distinct from old.brand_id
+ or new.author is distinct from old.author
+ or new.created_by is distinct from old.created_by
+ or new.created_at is distinct from old.created_at
+ or new.score_before is distinct from old.score_before
+ or new.score_after is distinct from old.score_after
+ or new.action_id is distinct from old.action_id
+ or new.agent_state is distinct from old.agent_state
+ or new.agent_state_at is distinct from old.agent_state_at
+ or new.agent_run is distinct from old.agent_run
+ then
+ raise exception 'content draft column is managed server-side'
+ using errcode = '42501';
+ end if;
+ return new;
+end;
+$$;
diff --git a/supabase/schema.sql b/supabase/schema.sql
index af173f41a..d87e4dccd 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -37052,6 +37052,120 @@ revoke execute on function public.refresh_mention_terms_daily(uuid, date, date)
comment on table public.mentions_perception_snapshots is
'The Perception tab''s default view (MS-09) per brand and window (7, 30 or 90 days, every platform and region, no topic or search), as mentions_perception returns it. Written by refresh_mentions_perception_snapshot; set aside when the brand''s competitors or name change, or its Perception rollups are rebuilt (00246).';
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00247_content_page_suggestions.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- ============================================================================
+-- 00247: a whole-page suggestion (Content Editor, Rewrite the page to these rules)
+-- ============================================================================
+-- Apply rules with Agent leaves at most 8 small edits a run, which can't
+-- bring a 19,000-character page to an 8,000-character Length (about 2% a
+-- run on prod, 2026-10-23). Rewrite the page to these rules has the Content
+-- Agent rewrite the whole page in one call, left as ONE suggestion the
+-- person compares with their page and accepts or rejects:
+--
+-- * kind 'page': after_text is the whole page's HTML, up to 500,000
+-- characters (the editor's body limit), not 20,000;
+-- * before_html: the page as the agent read it, which the editor checks
+-- the page against before applying it and puts back on Undo. A page
+-- suggestion has it; the others don't;
+-- * before_text stays '' for it, as for an insert.
+--
+-- Rows are still written by the server only; the decide RPC (00217) and
+-- RLS are unchanged.
+--
+-- content_drafts.agent_run says which run holds the draft ('write' or
+-- 'rewrite'), so every device knows a failed rewrite from a failed Start;
+-- 00219's guard keeps it server-set.
+
+alter table public.content_draft_suggestions
+ add column if not exists before_html text;
+
+alter table public.content_draft_suggestions
+ drop constraint if exists content_draft_suggestions_kind_check,
+ add constraint content_draft_suggestions_kind_check
+ check (kind in ('replace', 'insert', 'page'));
+
+alter table public.content_draft_suggestions
+ drop constraint if exists content_draft_suggestions_after_text_check,
+ add constraint content_draft_suggestions_after_text_check
+ check (char_length(after_text) between 1 and case when kind = 'page' then 500000 else 20000 end);
+
+alter table public.content_draft_suggestions
+ drop constraint if exists content_draft_suggestions_check,
+ add constraint content_draft_suggestions_check
+ check (kind in ('insert', 'page') or before_text <> '');
+
+alter table public.content_draft_suggestions
+ drop constraint if exists content_draft_suggestions_before_html_check,
+ add constraint content_draft_suggestions_before_html_check
+ check ((kind = 'page') = (before_html is not null)
+ and char_length(coalesce(before_html, '')) <= 500000);
+
+comment on column public.content_draft_suggestions.before_html is
+ 'A page suggestion''s page as the agent read it (kind ''page'', 00247): checked against the editor''s page before applying, and put back on Undo. Null for the others.';
+
+-- Which run holds the draft, or last held it (agent_state): Start with Agent
+-- ('write': a new page, or suggestions on a live one) or Rewrite the page to
+-- these rules ('rewrite'). The editor reads it to say which run failed and to
+-- try that one again, on any device: a failed rewrite tried again is a
+-- rewrite to compare, never a new page over the current one. Server-set,
+-- with agent_state.
+alter table public.content_drafts
+ add column if not exists agent_run text;
+
+alter table public.content_drafts
+ drop constraint if exists content_drafts_agent_run_check,
+ add constraint content_drafts_agent_run_check
+ check (agent_run is null or agent_run in ('write', 'rewrite'));
+
+comment on column public.content_drafts.agent_run is
+ 'Content Editor: the run that holds the draft or last held it (00247): ''write'' (Start with Agent) or ''rewrite'' (Rewrite the page to these rules). Server-set, with agent_state.';
+
+-- 00219's guard, with agent_run among the columns only the server sets.
+create or replace function public.guard_content_draft_server_columns()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+begin
+ -- A role that bypasses RLS is server-side (service role, migrations).
+ if (select rolbypassrls from pg_catalog.pg_roles where rolname = current_user) then
+ return new;
+ end if;
+
+ if tg_op = 'INSERT' then
+ if new.score_before is not null or new.score_after is not null then
+ raise exception 'content draft scores are set server-side'
+ using errcode = '42501';
+ end if;
+ if new.action_id is not null then
+ raise exception 'content draft action is set server-side'
+ using errcode = '42501';
+ end if;
+ if new.agent_state is not null or new.agent_state_at is not null
+ or new.agent_run is not null then
+ raise exception 'content draft agent state is set server-side'
+ using errcode = '42501';
+ end if;
+ elsif new.brand_id is distinct from old.brand_id
+ or new.author is distinct from old.author
+ or new.created_by is distinct from old.created_by
+ or new.created_at is distinct from old.created_at
+ or new.score_before is distinct from old.score_before
+ or new.score_after is distinct from old.score_after
+ or new.action_id is distinct from old.action_id
+ or new.agent_state is distinct from old.agent_state
+ or new.agent_state_at is distinct from old.agent_state_at
+ or new.agent_run is distinct from old.agent_run
+ then
+ raise exception 'content draft column is managed server-side'
+ using errcode = '42501';
+ end if;
+ return new;
+end;
+$$;
+
-- ─────────────────────────────────────────────────────────────────────────
-- migrations/00250_traffic_anonymous_visitors.sql
-- ─────────────────────────────────────────────────────────────────────────
diff --git a/web/src/app/api/mcp/content-drafts/[id]/suggestions/route.ts b/web/src/app/api/mcp/content-drafts/[id]/suggestions/route.ts
index 4d5470994..ae9181d8c 100644
--- a/web/src/app/api/mcp/content-drafts/[id]/suggestions/route.ts
+++ b/web/src/app/api/mcp/content-drafts/[id]/suggestions/route.ts
@@ -33,6 +33,12 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
{ status: 409 },
);
}
+ if (result === 'writing') {
+ return NextResponse.json(
+ { error: 'The Content Agent is writing this draft; suggest again once it has finished' },
+ { status: 409 },
+ );
+ }
if (!result) return NextResponse.json({ error: 'Draft not found' }, { status: 404 });
return NextResponse.json(result, { status: result.kept ? 201 : 200 });
} catch (err) {
diff --git a/web/src/lib/mcp/content.test.ts b/web/src/lib/mcp/content.test.ts
index 83710bfb2..74c33e54e 100644
--- a/web/src/lib/mcp/content.test.ts
+++ b/web/src/lib/mcp/content.test.ts
@@ -287,6 +287,19 @@ describe('suggestContentChangesFor', () => {
expect(db.writes).toEqual([]);
});
+ it('waits while Start or a rewrite holds the draft', async () => {
+ db.rows.content_drafts = draftRow({
+ agent_state: 'writing',
+ agent_state_at: new Date().toISOString(),
+ });
+ await expect(
+ suggestContentChangesFor(auth, 'd1', [
+ { kind: 'insert', passage: 1, after: '<p>x</p>', reason: 'y' },
+ ]),
+ ).resolves.toBe('writing');
+ expect(db.writes).toEqual([]);
+ });
+
it('leaves a published draft alone', async () => {
db.rows.content_drafts = draftRow({ status: 'published' });
await expect(
diff --git a/web/src/lib/mcp/content.ts b/web/src/lib/mcp/content.ts
index 788af51c1..700eddbcc 100644
--- a/web/src/lib/mcp/content.ts
+++ b/web/src/lib/mcp/content.ts
@@ -10,7 +10,7 @@ import {
import { classifyDomain, extractHostname, normalizeDomain } from '@/lib/citations/classify';
import { completeDraftTasks } from '@/lib/content/action-drafts';
import { CITED_DAYS, passageKey, quotedPassages } from '@/lib/content/cited-passages';
-import { contentEditorPath, isPageType, type PageType } from '@/lib/content/drafts';
+import { agentStateOf, contentEditorPath, isPageType, type PageType } from '@/lib/content/drafts';
import { IMPACT_PERIODS } from '@/lib/content/impact';
import { detectPageType, siteTypeOf } from '@/lib/content/page-types';
import { sanitizeDraftHtml } from '@/lib/content/sanitize-draft-html';
@@ -38,7 +38,7 @@ import {
const LIST_LIMIT = 100;
const DRAFT_COLUMNS =
- 'id, brand_id, title, status, method, page_type, author, source_url, body_html, action_id, prompt_ids, updated_at, brands!inner(organization_id, site_type, industry, shopping_mode_enabled), actions(action_no)';
+ 'id, brand_id, title, status, method, page_type, author, source_url, body_html, action_id, prompt_ids, updated_at, agent_state, agent_state_at, brands!inner(organization_id, site_type, industry, shopping_mode_enabled), actions(action_no)';
interface DraftRow {
id: string;
@@ -53,6 +53,8 @@ interface DraftRow {
action_id: string | null;
prompt_ids: string[] | null;
updated_at: string;
+ agent_state: string | null;
+ agent_state_at: string | null;
actions: { action_no: number } | { action_no: number }[] | null;
}
@@ -463,7 +465,9 @@ export async function addContentSourceFor(
* are numbered as get_content_draft lists them; what the editor can't apply
* is dropped with the reason. Null outside the organization; 'published' for
* a draft that is live already; 'open_suggestions' while a person still has
- * the latest batch's suggestions to decide.
+ * the latest batch's suggestions to decide; 'writing' while Start or a
+ * rewrite holds it (its answer, already charged, would be dropped over this
+ * batch).
*/
export async function suggestContentChangesFor(
auth: McpAuthContext,
@@ -473,12 +477,14 @@ export async function suggestContentChangesFor(
| { kept: number; batch_id: string | null; dropped: { index: number; reason: DroppedReason }[] }
| 'published'
| 'open_suggestions'
+ | 'writing'
| null
> {
const draft = await draftFor(auth, draftId);
if (!draft) return null;
if (draft.status === 'published') return 'published';
if ((await openSuggestionsOf(draft.id)).length) return 'open_suggestions';
+ if (agentStateOf(draft.agent_state, draft.agent_state_at) === 'writing') return 'writing';
const passages = draftPassages(draft.body_html);
// The targets only when a suggestion links: the sources read is the heavy one.
const linking = suggestions.some((s) => /<a\b/i.test(s.after));
diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.ts
index b05e4e327..e1d162ec9 100644
--- a/web/src/lib/mcp/server.ts
+++ b/web/src/lib/mcp/server.ts
@@ -1715,6 +1715,17 @@ export function createMcpServer(auth: McpAuthContext): McpServer {
isError: true,
};
}
+ if (result === 'writing') {
+ return {
+ content: [
+ {
+ type: 'text' as const,
+ text: 'The Content Agent is writing this draft; suggest again once it has finished',
+ },
+ ],
+ isError: true,
+ };
+ }
return result ? json(result) : notFound('Draft');
},
);