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): let the Content Agent link to the brand's pages and the draft's sources (#1371)

Cihanf2967cebc570
diff --git a/server/src/lib/content-agent.js b/server/src/lib/content-agent.js
index 031be4f5f..f6cc276ac 100644
--- a/server/src/lib/content-agent.js
+++ b/server/src/lib/content-agent.js
@@ -5,6 +5,7 @@ import { z } from 'zod';
import supabaseAdmin from '../config/supabase.js';
import { resolveModel } from './ai-provider.js';
import { contentBriefModelId, recordUsage } from './content-brief.js';
+import { linkAllowList, linkKey, linkTargetsPrompt, readLinkTargets } from './content-links.js';
import { pageTypeFormat } from './content-page-types.js';
import { getLanguageName } from './languages.js';
import { enforceImproveQuota } from './plan-guard.js';
@@ -25,6 +26,9 @@ export const MAX_AGENT_SUGGESTIONS = 8;
/** How long the model may take: the editor waits for it. */
const CALL_TIMEOUT_MS = 60_000;
+/** The most links one replace keeps (after_links, 00240). */
+const MAX_LINKS = 20;
+
/** The longest passage the agent may change: keepSuggestions skips longer ones. */
const MAX_PASSAGE_CHARS = 5_000;
@@ -40,8 +44,12 @@ export const HEADING_LIMITS = { h1: 70, other: 90 };
export const headingLimit = (tag) => (tag === 'h1' ? HEADING_LIMITS.h1 : HEADING_LIMITS.other);
/** The headings rule both agent prompts give the model (fix rules, Start Agent). */
+
export const HEADING_RULE = `- A heading stays a heading: one short line, an H1 up to ${HEADING_LIMITS.h1} characters and other headings up to ${HEADING_LIMITS.other}. Never write an answer, a sentence or a FAQ into a heading's replace; to answer under a heading, insert a paragraph after it.`;
+/** The links rule both agent prompts give the model: only the URLs listed, never invented. */
+export const LINK_RULE = `- Links: link only to a URL listed under the pages or sources you may link to, copied exactly, as <a href="URL">the words it explains</a>, in a replace's "after" or in an insert. Cite a source by linking the words it supports. Never invent a URL, never link a heading, and when no listed page fits, add no link.`;
+
/** The shortest answer a heading's replace may carry for it to go under the heading. */
const MIN_ANSWER_CHARS = 40;
@@ -90,7 +98,7 @@ export const suggestionsSchema = z.object({
after: z
.string()
.describe(
- `replace: the new words, as plain text (a heading stays one line: an H1 up to ${HEADING_LIMITS.h1} characters, others up to ${HEADING_LIMITS.other}); insert: the blocks to add, as simple HTML (h2, h3, p, ul, ol, li, strong, em).`,
+ `replace: the new words, as plain text with links only as <a href> to the URLs listed (a heading stays one line: an H1 up to ${HEADING_LIMITS.h1} characters, others up to ${HEADING_LIMITS.other}); insert: the blocks to add, as simple HTML (h2, h3, p, ul, ol, li, strong, em, a).`,
),
reason: z.string().describe('What the change does, in a few words.'),
rules: z.array(z.string()).describe('The keys of the rules it fixes.'),
@@ -103,9 +111,10 @@ const SYSTEM_PROMPT = `You are the Content Agent for Answer Engine Optimization
Rules for your suggestions:
- Fix only the rules listed. Each suggestion fixes one or more of them; put their keys in "rules".
-- A replace changes words inside one passage: copy "before" exactly as that passage has it (a phrase or a sentence), and write "after" as plain text that fits in its place.
-- An insert adds new blocks after a passage, as simple HTML (h2, h3, p, ul, ol, li, strong, em).
+- A replace changes words inside one passage: copy "before" exactly as that passage has it (a phrase or a sentence), and write "after" as plain text that fits in its place, with links only as the links rule below says.
+- An insert adds new blocks after a passage, as simple HTML (h2, h3, p, ul, ol, li, strong, em, and a for links).
${HEADING_RULE}
+${LINK_RULE}
- Never change a passage marked LOCKED: AI assistants quote its wording today. You may insert after it.
- Use only facts from the page and the brand. Never invent numbers, prices, dates, names, sources or quotes. When a rule needs a fact you don't have, write a placeholder in square brackets, e.g. [figure, source, year].
- Keep the page's voice and change as little as each rule needs. At most ${MAX_AGENT_SUGGESTIONS} suggestions.
@@ -154,10 +163,12 @@ const INSERT_TAGS = new Set([
/**
* An insert's HTML kept to the blocks the editor takes from an agent, with
- * no attributes; anything else is unwrapped to its text. The editor checks
- * it again where it is inserted, and every save checks the page.
+ * no attributes; anything else is unwrapped to its text. A link stays only
+ * to a URL in `links` (linkAllowList), with that URL, and never in a heading.
+ * The editor checks it again where it is inserted, and every save checks the
+ * page.
*/
-export function cleanInsertHtml(html) {
+export function cleanInsertHtml(html, links = null) {
const $ = cheerio.load(html || '', null, false);
$('script, style, iframe, object, embed, noscript, template, head, title').remove();
// The page has its H1, its title: an agent's heading is an H2 at most.
@@ -165,7 +176,15 @@ export function cleanInsertHtml(html) {
el.name = 'h2';
});
for (const el of $('*').get().reverse()) {
- if (!INSERT_TAGS.has(el.tagName?.toLowerCase())) {
+ const tag = el.tagName?.toLowerCase();
+ const href = tag === 'a' && links ? links.get(linkKey(el.attribs?.href)) : undefined;
+ const inHeading = $(el).parents('h1, h2, h3, h4, h5, h6').length > 0;
+ if (href && !inHeading && $(el).text().trim()) {
+ for (const name of Object.keys(el.attribs ?? {})) $(el).removeAttr(name);
+ $(el).attr('href', href);
+ continue;
+ }
+ if (!INSERT_TAGS.has(tag)) {
$(el).replaceWith($(el).contents());
continue;
}
@@ -174,6 +193,42 @@ export function cleanInsertHtml(html) {
return $.html().trim();
}
+/**
+ * Inline HTML's words and the links on them, { text, links: [{ start, end,
+ * href }] } with offsets into the text: runs of spaces and line breaks
+ * collapsed to one space (a non-breaking space stays), trimmed.
+ */
+export function inlineText(html) {
+ const $ = cheerio.load(html || '', null, false);
+ let text = '';
+ const links = [];
+ const add = (data) => {
+ const piece = data.replace(/[ \t\r\n\f]+/g, ' ');
+ text += text === '' || text.endsWith(' ') ? piece.replace(/^ /, '') : piece;
+ };
+ const walk = (nodes) => {
+ for (const node of nodes) {
+ if (node.type === 'text') add(node.data);
+ if (node.type !== 'tag') continue;
+ if (node.name === 'br') {
+ add(' ');
+ continue;
+ }
+ const start = text.length;
+ walk(node.children ?? []);
+ if (node.name !== 'a' || !node.attribs?.href) continue;
+ let from = start;
+ let to = text.length;
+ while (from < to && text[from] === ' ') from++;
+ while (to > from && text[to - 1] === ' ') to--;
+ if (to > from) links.push({ start: from, end: to, href: node.attribs.href });
+ }
+ };
+ walk($.root().contents().get());
+ const trimmed = text.replace(/ +$/, '');
+ return { text: trimmed, links: links.filter((link) => link.end <= trimmed.length) };
+}
+
const textOf = (html) =>
cheerio
.load(html || '', null, false)
@@ -213,10 +268,11 @@ function paragraph(text) {
* block when that is of the passage's kind; the rest is an insert. On a
* heading, words that answer its question ("What is X? X is …", the answer
* a sentence of MIN_ANSWER_CHARS or more) keep the question, and the answer
- * becomes the first paragraph under it.
+ * becomes the first paragraph under it. The words' links (to a URL in
+ * `links`) come with their offsets; a heading's words keep none.
*/
-export function splitReplace(after, tag) {
- const html = cleanInsertHtml(after);
+export function splitReplace(after, tag, links = null) {
+ const html = cleanInsertHtml(after, links);
const start = html.search(BLOCK_START);
let words = start === -1 ? html : html.slice(0, start);
let blocks = start === -1 ? '' : html.slice(start);
@@ -230,9 +286,9 @@ export function splitReplace(after, tag) {
}
}
// Line breaks and runs of spaces, not a non-breaking space the passage may keep.
- words = textOf(words)
- .replace(/[ \t\r\n\f]+/g, ' ')
- .trim();
+ const read = inlineText(words);
+ words = read.text;
+ const wordLinks = isHeading(tag) ? [] : read.links;
if (isHeading(tag)) {
// A question and its answer ("What is X? X is …"): the answer goes under
// the heading first, before any blocks that came with it. A subtitle that
@@ -248,7 +304,7 @@ export function splitReplace(after, tag) {
blocks = paragraph(answered[2]) + blocks;
}
}
- return { words, blocks: blocks.trim() };
+ return { words, links: wordLinks, blocks: blocks.trim() };
}
/**
@@ -258,9 +314,11 @@ export function splitReplace(after, tag) {
* each change once. A replace that carries blocks, or an answer on a
* heading, is split into a replace and an insert after it (splitReplace);
* one that would still grow a heading past its headingLimit is dropped (a
- * long heading may still be shortened).
+ * long heading may still be shortened). Links stay only to the URLs in
+ * `links` (linkAllowList): a replace's go in after_links, by offset into its
+ * words, an insert's in its HTML.
*/
-export function keepSuggestions(raw, passages, lockedKeys, ruleKeys) {
+export function keepSuggestions(raw, passages, lockedKeys, ruleKeys, links = null) {
const kept = [];
const seen = new Set();
for (const s of raw) {
@@ -287,13 +345,17 @@ export function keepSuggestions(raw, passages, lockedKeys, ruleKeys) {
// replace never leaves a question without its answer.
let changes;
if (s.kind !== 'replace') {
- changes = [insertOf(cleanInsertHtml(s.after))];
+ changes = [insertOf(cleanInsertHtml(s.after, links))];
} else {
if (lockedKeys.has(passageKey(passage.text))) continue;
const before = s.before.trim();
if (!before || !passage.text.includes(before)) continue;
- const { words, blocks } = splitReplace(s.after, passage.tag);
- const changed = words && words !== before;
+ const split = splitReplace(s.after, passage.tag, links);
+ const { words, blocks } = split;
+ // As many as a suggestion may keep (00240).
+ const wordLinks = split.links.slice(0, MAX_LINKS);
+ // Linking words the passage already has is a change too.
+ const changed = words && (words !== before || wordLinks.length > 0);
if (changed && (words.length > 2000 || growsPastLimit(passage, before, words))) continue;
changes = [
changed && {
@@ -303,6 +365,7 @@ export function keepSuggestions(raw, passages, lockedKeys, ruleKeys) {
block_text: passage.text,
before_text: before,
after_text: words,
+ ...(wordLinks.length ? { after_links: wordLinks } : {}),
reason,
rule_keys: rules,
},
@@ -341,7 +404,15 @@ export function promptPassages(passages) {
}
/** What the model is told: the brand, the page's passages, and the rules to fix. */
-export function buildFixPrompt({ brand, draft, passages, more = false, lockedKeys, input }) {
+export function buildFixPrompt({
+ brand,
+ draft,
+ passages,
+ more = false,
+ lockedKeys,
+ input,
+ linkTargets = '',
+}) {
const lines = passages.map((p, i) => {
const locked = lockedKeys.has(passageKey(p.text)) ? ', LOCKED' : '';
return `[${i + 1}] (${p.tag}${locked}) ${p.text}`;
@@ -358,7 +429,7 @@ Page type: ${pageTypeFormat(draft.page_type)}
Rules the page doesn't meet yet (key: rule — what it asks and how the page reads now):
${rules.join('\n')}
-${own.length ? `\nThe writer's own rules, to follow in every change:\n${own.join('\n')}\n` : ''}
+${own.length ? `\nThe writer's own rules, to follow in every change:\n${own.join('\n')}\n` : ''}${linkTargets ? `\n${linkTargets}\n` : ''}
The page, passage by passage:
${lines.join('\n')}
@@ -393,7 +464,7 @@ 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')
+ .select('id, brand_id, title, body_html, page_type, action_id, status, source_url')
.eq('id', draftId)
.maybeSingle();
if (draftError) throw draftError;
@@ -425,11 +496,27 @@ export async function fixDraftRules({ draftId, brandId, input }) {
await enforceImproveQuota(brand.organization_id, modelId);
const lockedKeys = new Set(input.locked.map(passageKey));
+ const ruleKeys = new Set(input.rules.map((r) => r.key));
+ // Where it may link: the brand's pages and the draft's sources (A).
+ const targets = await readLinkTargets({
+ brandId,
+ draftId,
+ sourceUrl: draft.source_url,
+ ruleKeys,
+ });
const { object, usage } = await generateObject({
model: resolveModel(modelId),
schema: suggestionsSchema,
system: SYSTEM_PROMPT,
- prompt: buildFixPrompt({ brand, draft, passages, more, lockedKeys, input }),
+ prompt: buildFixPrompt({
+ brand,
+ draft,
+ passages,
+ more,
+ lockedKeys,
+ input,
+ linkTargets: linkTargetsPrompt(targets, ruleKeys),
+ }),
abortSignal: AbortSignal.timeout(CALL_TIMEOUT_MS),
});
await recordUsage({ organizationId: brand.organization_id, draftId, modelId, usage });
@@ -438,7 +525,8 @@ export async function fixDraftRules({ draftId, brandId, input }) {
object.suggestions,
passages,
lockedKeys,
- new Set(input.rules.map((r) => r.key)),
+ ruleKeys,
+ linkAllowList(targets),
);
if (!rows.length) return { count: 0, batchId: null };
diff --git a/server/src/lib/content-agent.test.js b/server/src/lib/content-agent.test.js
index bc831729a..e6ef6c337 100644
--- a/server/src/lib/content-agent.test.js
+++ b/server/src/lib/content-agent.test.js
@@ -37,7 +37,12 @@ vi.mock('./plan-guard.js', async (importOriginal) => ({
...(await importOriginal()),
enforceImproveQuota: (...args) => enforceImproveQuota(...args),
}));
-vi.mock('./logger.js', () => ({ logger: { error: vi.fn() } }));
+vi.mock('./logger.js', () => ({ logger: { error: vi.fn(), warn: vi.fn() } }));
+const readLinkTargets = vi.fn();
+vi.mock('./content-links.js', async (importOriginal) => ({
+ ...(await importOriginal()),
+ readLinkTargets: (...args) => readLinkTargets(...args),
+}));
const {
buildFixPrompt,
@@ -47,11 +52,13 @@ const {
keepSuggestions,
growsPastLimit,
HEADING_LIMITS,
+ inlineText,
MAX_PROMPT_PASSAGE_CHARS,
passageKey,
promptPassages,
splitReplace,
} = await import('./content-agent.js');
+const { linkKey, NO_LINK_TARGETS } = await import('./content-links.js');
const { PlanLimitError } = await import('./plan-guard.js');
const BODY =
@@ -94,6 +101,7 @@ beforeEach(() => {
};
generateObject.mockReset();
enforceImproveQuota.mockReset().mockResolvedValue(undefined);
+ readLinkTargets.mockReset().mockResolvedValue(NO_LINK_TARGETS);
});
describe('the page as the agent reads it', () => {
@@ -318,7 +326,7 @@ describe('a replace on a heading', () => {
});
it('keeps a heading with a second clause, and a paragraph replace as it was', () => {
- expect(splitReplace('AEO or SEO? Which matters more in 2026', 'h2')).toEqual({
+ expect(splitReplace('AEO or SEO? Which matters more in 2026', 'h2')).toMatchObject({
words: 'AEO or SEO? Which matters more in 2026',
blocks: '',
});
@@ -330,13 +338,13 @@ describe('a replace on a heading', () => {
'AEO とは? AEO は AI アシスタントの回答に引用されるための最適化の方法です。説明します。',
'h2',
),
- ).toEqual({
+ ).toMatchObject({
words: 'AEO とは?',
blocks: '<p>AEO は AI アシスタントの回答に引用されるための最適化の方法です。説明します。</p>',
});
// A non-breaking space stays one, as the passage keeps it.
expect(splitReplace('Pour\u00a0slowly', 'p').words).toBe('Pour\u00a0slowly');
- expect(splitReplace('Use 15 g of coffee. Then pour.', 'p')).toEqual({
+ expect(splitReplace('Use 15 g of coffee. Then pour.', 'p')).toMatchObject({
words: 'Use 15 g of coffee. Then pour.',
blocks: '',
});
@@ -348,7 +356,7 @@ describe('a replace on a heading', () => {
'What is LLM SEO? LLM SEO optimizes pages for large language models.<ul><li>a</li></ul>',
'h2',
),
- ).toEqual({
+ ).toMatchObject({
words: 'What is LLM SEO?',
blocks: '<p>LLM SEO optimizes pages for large language models.</p><ul><li>a</li></ul>',
});
@@ -357,7 +365,7 @@ describe('a replace on a heading', () => {
'<h2>What is LLM SEO? LLM SEO optimizes pages for large language models.</h2><p>More.</p>',
'h2',
),
- ).toEqual({
+ ).toMatchObject({
words: 'What is LLM SEO?',
blocks: '<p>LLM SEO optimizes pages for large language models.</p><p>More.</p>',
});
@@ -365,13 +373,13 @@ describe('a replace on a heading', () => {
it('keeps a subtitle that fits, and splits after a full-width ? with no space', () => {
const subtitle = 'What is AEO? The Complete Guide to Answer Engine Optimization';
- expect(splitReplace(subtitle, 'h1')).toEqual({ words: subtitle, blocks: '' });
+ expect(splitReplace(subtitle, 'h1')).toMatchObject({ words: subtitle, blocks: '' });
expect(
splitReplace(
'AEOとは?AEOはAIアシスタントの回答に引用されるための最適化の方法です。詳しく順番に説明します。',
'h2',
),
- ).toEqual({
+ ).toMatchObject({
words: 'AEOとは?',
blocks:
'<p>AEOはAIアシスタントの回答に引用されるための最適化の方法です。詳しく順番に説明します。</p>',
@@ -384,13 +392,155 @@ describe('a replace on a heading', () => {
});
it('moves blocks sent with a paragraph replace after it', () => {
- expect(splitReplace('<p>Use 15 g.</p><ul><li>a scale</li></ul>', 'p')).toEqual({
+ expect(splitReplace('<p>Use 15 g.</p><ul><li>a scale</li></ul>', 'p')).toMatchObject({
words: 'Use 15 g.',
blocks: '<ul><li>a scale</li></ul>',
});
});
});
+/**
+ * Content Agent rule gaps, A: links only to the brand's pages and the draft's
+ * sources it was given, a replace's beside its words, an insert's in its HTML.
+ */
+describe('links to the pages and sources given', () => {
+ const page = draftPassages(
+ '<h2>Pricing</h2><p>See our plans for teams.</p><p>Studies show it works.</p>',
+ );
+ const links = new Map(
+ ['https://acme.example/pricing', 'https://research.example/study'].map((url) => [
+ linkKey(url),
+ url,
+ ]),
+ );
+ const keep = (over, ruleKeys = ['internalLinks']) =>
+ keepSuggestions(
+ [suggestion({ passage: 2, before: 'See our plans for teams.', rules: ruleKeys, ...over })],
+ page,
+ new Set(),
+ new Set(ruleKeys),
+ links,
+ );
+
+ it('keeps a replace’s link to a listed page, by its words, with the page’s URL', () => {
+ const [kept] = keep({
+ after:
+ 'See <a href="https://www.acme.example/pricing/?utm_source=x">our plans</a> for teams.',
+ });
+ expect(kept).toMatchObject({
+ kind: 'replace',
+ after_text: 'See our plans for teams.',
+ after_links: [{ start: 4, end: 13, href: 'https://acme.example/pricing' }],
+ rule_keys: ['internalLinks'],
+ });
+ });
+
+ it('unwraps a link to anything not listed, and drops what then changes nothing', () => {
+ expect(
+ keep({ after: 'See <a href="https://made-up.example/x">our plans</a> for teams.' }),
+ ).toMatchObject([]);
+ const [kept] = keep({ after: 'See <a href="https://made-up.example/x">our team plans</a>.' });
+ expect(kept.after_text).toBe('See our team plans.');
+ expect(kept).not.toHaveProperty('after_links');
+ });
+
+ it('keeps an insert’s link to a listed source, never one in a heading', () => {
+ const [kept] = keepSuggestions(
+ [
+ suggestion({
+ kind: 'insert',
+ passage: 3,
+ before: '',
+ after:
+ '<h3><a href="https://research.example/study">Study</a></h3><p>A <a href="https://research.example/study" target="_blank" onclick="x()">2025 study</a> found it.</p>',
+ rules: ['citeInline'],
+ }),
+ ],
+ page,
+ new Set(),
+ new Set(['citeInline']),
+ links,
+ );
+ expect(kept.after_text).toBe(
+ '<h3>Study</h3><p>A <a href="https://research.example/study">2025 study</a> found it.</p>',
+ );
+ });
+
+ it('keeps at most 20 links on a replace, as the table allows', () => {
+ const many = Array.from(
+ { length: 22 },
+ (_, i) => `<a href="https://acme.example/pricing">plan ${i}</a>`,
+ ).join(' ');
+ const [kept] = keep({ after: `See ${many} for teams.` });
+ expect(kept.after_links).toHaveLength(20);
+ });
+
+ it('keeps no link without targets, as before', () => {
+ const [kept] = keepSuggestions(
+ [
+ suggestion({
+ kind: 'insert',
+ passage: 3,
+ before: '',
+ after: '<p>A <a href="https://research.example/study">study</a>.</p>',
+ }),
+ ],
+ page,
+ new Set(),
+ new Set(),
+ );
+ expect(kept.after_text).toBe('<p>A study.</p>');
+ });
+
+ it('reads inline words and their links, spaces collapsed', () => {
+ expect(inlineText('Read <a href="u"> the guide </a><br>now')).toEqual({
+ text: 'Read the guide now',
+ links: [{ start: 5, end: 14, href: 'u' }],
+ });
+ });
+
+ it('gives the model the targets for the link rules asked, and keeps the links', async () => {
+ readLinkTargets.mockResolvedValue({
+ own: [{ url: 'https://acme.example/brew-guide', title: 'Brew guide' }],
+ sources: [{ url: 'https://research.example/study', title: 'Coffee study' }],
+ });
+ generateObject.mockResolvedValue({
+ object: {
+ suggestions: [
+ suggestion({
+ after:
+ 'Use good coffee (see <a href="https://acme.example/brew-guide">our brew guide</a>).',
+ rules: ['internalLinks'],
+ }),
+ ],
+ },
+ usage: {},
+ });
+ const result = await fixDraftRules({
+ draftId: DRAFT,
+ brandId: BRAND,
+ input: input({ rules: [{ key: 'internalLinks', name: 'Internal links', detail: '0 of 3' }] }),
+ });
+
+ expect(readLinkTargets).toHaveBeenCalledWith(
+ expect.objectContaining({ brandId: BRAND, draftId: DRAFT }),
+ );
+ const { prompt, system } = generateObject.mock.calls[0][0];
+ expect(prompt).toContain(
+ "Pages on the brand's site you may link to (internal links):\n- Brew guide — https://acme.example/brew-guide",
+ );
+ // Only the rule asked for: no outbound list.
+ expect(prompt).not.toContain('Sources you may link to');
+ expect(system).toContain('Never invent a URL');
+ expect(result.count).toBe(1);
+ const batch = writes.find((w) => w.table === 'content_draft_suggestions');
+ expect(batch.value[0]).toMatchObject({
+ after_text: 'Use good coffee (see our brew guide).',
+ after_links: [{ start: 21, end: 35, href: 'https://acme.example/brew-guide' }],
+ });
+ });
+});
+
describe('cleanInsertHtml', () => {
it('makes an agent’s H1 an H2: the page has its title', () => {
expect(cleanInsertHtml('<h1 class="x">New title</h1><p>Text</p>')).toBe(
diff --git a/server/src/lib/content-links.js b/server/src/lib/content-links.js
new file mode 100644
index 000000000..82be55d65
--- /dev/null
+++ b/server/src/lib/content-links.js
@@ -0,0 +1,164 @@
+import supabaseAdmin from '../config/supabase.js';
+import { logger } from './logger.js';
+import { ownDomainMatcher } from './response-parser.js';
+
+/**
+ * Where the Content Agent may link (Content Agent rule gaps, A): the brand's
+ * own pages for internal links, and the sources the draft keeps for outbound
+ * links and inline citations. The agent links only to these, by their URL;
+ * keepSuggestions unwraps any other link, so it never invents one.
+ */
+
+/** No targets: every link an agent writes is unwrapped. */
+export const NO_LINK_TARGETS = Object.freeze({ own: [], sources: [] });
+
+/** The brand's pages offered, the most cited and visited first. */
+export const MAX_OWN_PAGES = 40;
+/** The draft's sources offered, as the Sources tab lists them (its top 20). */
+export const MAX_SOURCE_PAGES = 20;
+
+/** Query parameters that only track a visit. */
+const TRACKING = /^(utm_\w+|gclid|fbclid|msclkid|mc_cid|mc_eid|ref)$/i;
+
+/**
+ * A URL as links compare: an http(s) address, its host lower-cased without
+ * www, no hash, no tracking parameters, no trailing slash. Null for anything else.
+ */
+export function linkKey(url) {
+ let parsed;
+ try {
+ parsed = new URL(String(url ?? '').trim());
+ } catch {
+ return null;
+ }
+ if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+ const host = parsed.hostname.toLowerCase().replace(/^www\./, '');
+ const params = [...parsed.searchParams].filter(([name]) => !TRACKING.test(name));
+ const search = params.length ? `?${new URLSearchParams(params).toString()}` : '';
+ const path = parsed.pathname.replace(/\/+$/, '');
+ return `${host}${path}${search}`;
+}
+
+/** A URL as a link keeps it: without tracking parameters or a hash; null when not http(s). */
+export function linkHref(url) {
+ if (!linkKey(url)) return null;
+ const parsed = new URL(String(url).trim());
+ for (const name of [...parsed.searchParams.keys()]) {
+ if (TRACKING.test(name)) parsed.searchParams.delete(name);
+ }
+ parsed.hash = '';
+ return parsed.toString();
+}
+
+const clean = (text) =>
+ String(text ?? '')
+ .replace(/\s+/g, ' ')
+ .trim();
+
+/**
+ * The draft's link targets: `own` (the brand's pages) and `sources` (pages AI
+ * answers cite for the draft's prompts, without the brand's own and its
+ * competitors', without the ones the person left out, with the ones they
+ * added), each { url, title }. A failed read leaves its list empty: the agent
+ * then links nothing there, as before.
+ */
+export async function readLinkTargets({ brandId, draftId, sourceUrl, ruleKeys }) {
+ // Each list is read only for the rules that use it.
+ const wantsOwn = ruleKeys.has('internalLinks');
+ const wantsSources = ruleKeys.has('outboundLinks') || ruleKeys.has('citeInline');
+ if (!wantsOwn && !wantsSources) return NO_LINK_TARGETS;
+ const none = { data: null, error: null };
+ const [pagesRead, sourcesRead, choicesRead] = await Promise.all([
+ wantsOwn
+ ? supabaseAdmin
+ .from('site_pages')
+ .select('url, title, h1')
+ .eq('brand_id', brandId)
+ // Not fetched yet, or answered: 0 is a fetch that failed outright (00104).
+ .or('fetch_status.is.null,and(fetch_status.gte.200,fetch_status.lt.400)')
+ .order('ai_citations', { ascending: false })
+ .order('ga_sessions', { ascending: false })
+ .limit(MAX_OWN_PAGES + 1)
+ : none,
+ wantsSources
+ ? supabaseAdmin.rpc('content_draft_sources', { p_draft_id: draftId, p_days: 30 })
+ : none,
+ wantsSources
+ ? supabaseAdmin
+ .from('content_draft_sources')
+ .select('ref, included, added')
+ .eq('draft_id', draftId)
+ .eq('kind', 'cited_page')
+ : none,
+ ]);
+ for (const [what, read] of [
+ ['site pages', pagesRead],
+ ['sources', sourcesRead],
+ ['source choices', choicesRead],
+ ]) {
+ if (read.error) {
+ logger.warn({ err: read.error, draftId }, `[content-links] reading ${what} failed`);
+ }
+ }
+
+ const seen = new Set([linkKey(sourceUrl)].filter(Boolean));
+ const take = (list, max, page) => {
+ const key = linkKey(page.url);
+ if (!key || seen.has(key) || list.length >= max) return;
+ seen.add(key);
+ const url = linkHref(page.url);
+ list.push({ url, title: clean(page.title) || url });
+ };
+
+ const own = [];
+ for (const page of pagesRead.error ? [] : (pagesRead.data ?? [])) {
+ take(own, MAX_OWN_PAGES, { url: page.url, title: page.title || page.h1 });
+ }
+
+ const data = sourcesRead.error ? null : sourcesRead.data;
+ // Without the read, competitors can't be told apart: no outbound targets.
+ if (!data) return { own, sources: [] };
+ const choices = choicesRead.error ? [] : (choicesRead.data ?? []);
+ const leftOut = new Set(choices.filter((c) => !c.included).map((c) => linkKey(c.ref)));
+ // The brand's and its competitors' own sites, a domain written with a path too.
+ const closed = ownDomainMatcher([
+ ...(data.brandDomains ?? []),
+ ...(data.competitorDomains ?? []),
+ ]);
+ const sources = [];
+ const candidates = [
+ ...(data.citedPages ?? []),
+ // Added by the person in the Sources tab: kept, even with no answer citing them yet.
+ ...choices.filter((c) => c.added && c.included).map((c) => ({ url: c.ref, title: '' })),
+ ];
+ for (const page of candidates) {
+ if (leftOut.has(linkKey(page.url)) || closed(page.url)) continue;
+ take(sources, MAX_SOURCE_PAGES, page);
+ }
+ return { own, sources };
+}
+
+/** The targets as the model reads them, by the rules asked for; '' when there are none. */
+export function linkTargetsPrompt(targets, ruleKeys) {
+ const lines = (list) => list.map((p) => `- ${p.title} — ${p.url}`).join('\n');
+ const parts = [];
+ if (targets.own.length && ruleKeys.has('internalLinks')) {
+ parts.push(
+ `Pages on the brand's site you may link to (internal links):\n${lines(targets.own)}`,
+ );
+ }
+ if (targets.sources.length && (ruleKeys.has('outboundLinks') || ruleKeys.has('citeInline'))) {
+ parts.push(
+ `Sources you may link to and cite (outbound links, inline citations):\n${lines(targets.sources)}`,
+ );
+ }
+ return parts.join('\n\n');
+}
+
+/**
+ * The URL a link may keep, by its key: every target's. A link to anything
+ * else is unwrapped.
+ */
+export function linkAllowList(targets) {
+ return new Map([...targets.own, ...targets.sources].map((p) => [linkKey(p.url), p.url]));
+}
diff --git a/server/src/lib/content-links.test.js b/server/src/lib/content-links.test.js
new file mode 100644
index 000000000..85cecc9b9
--- /dev/null
+++ b/server/src/lib/content-links.test.js
@@ -0,0 +1,168 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * Where the Content Agent may link (Content Agent rule gaps, A): the brand's
+ * own pages, and the draft's sources without the brand's and competitors'
+ * own or the ones the person left out.
+ */
+
+/** Table reads, and RPC answers (the sources RPC shares its name with the choices table). */
+let reads;
+let rpcs;
+const calls = [];
+
+vi.mock('../config/supabase.js', () => ({
+ default: {
+ from: (table) => {
+ calls.push(table);
+ const chain = {
+ select: () => chain,
+ eq: () => chain,
+ or: () => chain,
+ order: () => chain,
+ limit: async () => reads[table],
+ then: (resolve) => resolve(reads[table]),
+ };
+ return chain;
+ },
+ rpc: async (name) => (calls.push(`rpc:${name}`), rpcs[name]),
+ },
+}));
+vi.mock('./logger.js', () => ({ logger: { warn: vi.fn() } }));
+
+const { linkAllowList, linkHref, linkKey, linkTargetsPrompt, readLinkTargets } =
+ await import('./content-links.js');
+
+const LINK_RULES = new Set(['internalLinks', 'outboundLinks']);
+
+beforeEach(() => {
+ calls.length = 0;
+ reads = {
+ site_pages: {
+ data: [
+ { url: 'https://acme.example/pricing', title: 'Pricing', h1: 'Plans' },
+ { url: 'https://acme.example/guides/brew', title: null, h1: 'Brew guide' },
+ { url: 'https://acme.example/guides/brew/', title: 'Duplicate', h1: null },
+ ],
+ error: null,
+ },
+ // The person's choices in the Sources tab.
+ content_draft_sources: {
+ data: [
+ { ref: 'https://forum.example/thread', included: false, added: false },
+ { ref: 'https://standards.example/spec', included: true, added: true },
+ ],
+ error: null,
+ },
+ };
+ rpcs = {
+ content_draft_sources: {
+ data: {
+ citedPages: [
+ { url: 'https://research.example/study?utm_source=chatgpt.com', title: 'Coffee study' },
+ { url: 'https://www.rival.example/compare', title: 'Rival compares' },
+ { url: 'https://shop.other-rival.example/x', title: 'Other rival' },
+ { url: 'https://blog.acme.example/post', title: 'Our blog' },
+ { url: 'https://forum.example/thread', title: 'A thread' },
+ ],
+ brandDomains: ['acme.example'],
+ // A competitor's domain may be written with a path.
+ competitorDomains: ['rival.example', 'other-rival.example/en'],
+ },
+ error: null,
+ },
+ };
+});
+
+describe('linkKey', () => {
+ it('compares links without www, tracking, a hash or a trailing slash', () => {
+ expect(linkKey('https://WWW.Acme.example/Pricing/?utm_source=x&plan=pro#top')).toBe(
+ 'acme.example/Pricing?plan=pro',
+ );
+ expect(linkKey('https://acme.example/')).toBe('acme.example');
+ expect(linkKey('mailto:[email protected]')).toBeNull();
+ expect(linkKey('/pricing')).toBeNull();
+ expect(linkHref('https://www.acme.example/a/?utm_source=chatgpt.com&plan=pro#top')).toBe(
+ 'https://www.acme.example/a/?plan=pro',
+ );
+ });
+});
+
+describe('readLinkTargets', () => {
+ it("offers the brand's pages and the kept sources, never its own or a competitor's", async () => {
+ const targets = await readLinkTargets({
+ brandId: 'b1',
+ draftId: 'd1',
+ sourceUrl: 'https://acme.example/pricing',
+ ruleKeys: LINK_RULES,
+ });
+
+ // The draft's own page and a duplicate left out; a title, else its H1.
+ expect(targets.own).toEqual([{ url: 'https://acme.example/guides/brew', title: 'Brew guide' }]);
+ // Tracking parameters off the link the page will keep.
+ expect(targets.sources.map((s) => s.url)).toEqual([
+ 'https://research.example/study',
+ 'https://standards.example/spec',
+ ]);
+ });
+
+ it('reads only the list the rules asked for need', async () => {
+ const targets = await readLinkTargets({
+ brandId: 'b1',
+ draftId: 'd1',
+ sourceUrl: null,
+ ruleKeys: new Set(['internalLinks']),
+ });
+ expect(calls).toEqual(['site_pages']);
+ expect(targets.sources).toEqual([]);
+ expect(targets.own).toHaveLength(2);
+ });
+
+ it('reads nothing when no link rule is asked for', async () => {
+ const targets = await readLinkTargets({
+ brandId: 'b1',
+ draftId: 'd1',
+ sourceUrl: null,
+ ruleKeys: new Set(['faq']),
+ });
+ expect(targets).toEqual({ own: [], sources: [] });
+ expect(calls).toEqual([]);
+ });
+
+ it('leaves a list empty when its read fails', async () => {
+ reads.site_pages = { data: null, error: { message: 'down' } };
+ rpcs.content_draft_sources = { data: null, error: { message: 'down' } };
+ const targets = await readLinkTargets({
+ brandId: 'b1',
+ draftId: 'd1',
+ sourceUrl: null,
+ ruleKeys: LINK_RULES,
+ });
+ expect(targets).toEqual({ own: [], sources: [] });
+ });
+});
+
+describe('the targets as the model and the check read them', () => {
+ const targets = {
+ own: [{ url: 'https://acme.example/pricing', title: 'Pricing' }],
+ sources: [{ url: 'https://research.example/study', title: 'Coffee study' }],
+ };
+
+ it('lists only what the rules asked for need', () => {
+ expect(linkTargetsPrompt(targets, new Set(['internalLinks']))).toBe(
+ "Pages on the brand's site you may link to (internal links):\n- Pricing — https://acme.example/pricing",
+ );
+ expect(linkTargetsPrompt(targets, new Set(['citeInline']))).toContain(
+ '- Coffee study — https://research.example/study',
+ );
+ expect(linkTargetsPrompt(targets, new Set(['faq']))).toBe('');
+ });
+
+ it('allows each target by its key, giving back its URL', () => {
+ const allow = linkAllowList(targets);
+ expect(allow.get(linkKey('https://www.acme.example/pricing/'))).toBe(
+ 'https://acme.example/pricing',
+ );
+ expect(allow.get(linkKey('https://made-up.example/'))).toBeUndefined();
+ });
+});
diff --git a/server/src/lib/content-writer.js b/server/src/lib/content-writer.js
index ba05fff41..ef4779309 100644
--- a/server/src/lib/content-writer.js
+++ b/server/src/lib/content-writer.js
@@ -5,6 +5,7 @@ import supabaseAdmin from '../config/supabase.js';
import { resolveModel } from './ai-provider.js';
import {
HEADING_RULE,
+ LINK_RULE,
MAX_AGENT_SUGGESTIONS,
draftPassages,
hasOpenSuggestions,
@@ -14,6 +15,7 @@ import {
suggestionsSchema,
} from './content-agent.js';
import { contentBriefModelId, rebuildSources, recordUsage } from './content-brief.js';
+import { linkAllowList, linkTargetsPrompt, readLinkTargets } from './content-links.js';
import { pageTypeFormat } from './content-page-types.js';
import { getLanguageName } from './languages.js';
import { logger } from './logger.js';
@@ -103,9 +105,10 @@ const SUGGEST_SYSTEM_PROMPT = `You are the Content Agent for Answer Engine Optim
Rules for your suggestions:
- Make the page answer the questions and AI searches listed, follow the brief when there is one, and meet the rules listed.
-- A replace changes words inside one passage: copy "before" exactly as that passage has it (a phrase or a sentence), and write "after" as plain text that fits in its place.
-- An insert adds new blocks after a passage, as simple HTML (h2, h3, p, ul, ol, li, strong, em): a missing section, a direct answer, an FAQ.
+- A replace changes words inside one passage: copy "before" exactly as that passage has it (a phrase or a sentence), and write "after" as plain text that fits in its place, with links only as the links rule below says.
+- An insert adds new blocks after a passage, as simple HTML (h2, h3, p, ul, ol, li, strong, em, and a for links): a missing section, a direct answer, an FAQ.
${HEADING_RULE}
+${LINK_RULE}
- Never change a passage marked LOCKED: AI assistants quote its wording today. You may insert after it.
- Put the keys of the rules a change meets in "rules" (none when it meets none).
- Use only facts from the page and the brand. Never invent numbers, prices, dates, names, sources or quotes; write a placeholder in square brackets instead, e.g. [figure, source, year].
@@ -181,6 +184,7 @@ export function buildWritePrompt({
passages,
more = false,
lockedKeys,
+ linkTargets = '',
}) {
const { sources } = input;
const rules = input.rules.map((r) => `${r.key}: ${r.name}${r.detail ? ` — ${r.detail}` : ''}`);
@@ -219,7 +223,7 @@ ${list(sources.pages.map((p) => p.url))}
Rules (key: rule — what it asks):
${list(rules)}
-${own.length ? `\nThe writer's own rules:\n${own.join('\n')}\n` : ''}
+${own.length ? `\nThe writer's own rules:\n${own.join('\n')}\n` : ''}${linkTargets ? `\n${linkTargets}\n` : ''}
${page}
Write in ${getLanguageName(brand?.language)}.`;
@@ -423,11 +427,29 @@ export async function runDraftWriting({ draft, brand, model, modelId, input }) {
const { passages, more } = promptPassages(draftPassages(draft.body_html));
if (!passages.length) throw new Error('The page has no text to improve');
const lockedKeys = new Set(input.locked.map(passageKey));
+ const ruleKeys = new Set(input.rules.map((r) => r.key));
+ // 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: suggestionsSchema,
system: SUGGEST_SYSTEM_PROMPT,
- prompt: buildWritePrompt({ brand, draft, prompts, brief, input, passages, more, lockedKeys }),
+ prompt: buildWritePrompt({
+ brand,
+ draft,
+ prompts,
+ brief,
+ input,
+ passages,
+ more,
+ lockedKeys,
+ linkTargets: linkTargetsPrompt(targets, ruleKeys),
+ }),
abortSignal: AbortSignal.timeout(CALL_TIMEOUT_MS),
});
await recordUsage({ organizationId: brand.organization_id, draftId: draft.id, modelId, usage });
@@ -435,7 +457,8 @@ export async function runDraftWriting({ draft, brand, model, modelId, input }) {
object.suggestions,
passages,
lockedKeys,
- new Set(input.rules.map((r) => r.key)),
+ ruleKeys,
+ linkAllowList(targets),
);
if (!rows.length) throw new Error('The agent left no suggestion it could place');
// A batch that landed during the run (Fix open rules, the API) stays the
diff --git a/server/src/lib/content-writer.test.js b/server/src/lib/content-writer.test.js
index be262d94d..f70dfdc56 100644
--- a/server/src/lib/content-writer.test.js
+++ b/server/src/lib/content-writer.test.js
@@ -63,7 +63,12 @@ vi.mock('./plan-guard.js', async (importOriginal) => ({
...(await importOriginal()),
enforceImproveQuota: (...args) => enforceImproveQuota(...args),
}));
-vi.mock('./logger.js', () => ({ logger: { error: vi.fn(), info: vi.fn() } }));
+vi.mock('./logger.js', () => ({ logger: { error: vi.fn(), info: vi.fn(), warn: vi.fn() } }));
+const readLinkTargets = vi.hoisted(() => vi.fn());
+vi.mock('./content-links.js', async (importOriginal) => ({
+ ...(await importOriginal()),
+ readLinkTargets: (...args) => readLinkTargets(...args),
+}));
const hasOpenSuggestions = vi.hoisted(() => vi.fn());
vi.mock('./content-agent.js', async (importOriginal) => ({
...(await importOriginal()),
@@ -126,6 +131,7 @@ const page = {
};
beforeEach(() => {
+ readLinkTargets.mockReset().mockResolvedValue({ own: [], sources: [] });
writes = [];
rpcCalls = [];
reads = [];
@@ -395,6 +401,11 @@ describe('runDraftWriting on an existing page', () => {
expect(generateObject.mock.calls[0][0].system).toContain(
'Never write an answer, a sentence or a FAQ into a heading',
);
+ // Links only to the pages and sources listed (A); none asked for here.
+ expect(generateObject.mock.calls[0][0].system).toContain('Never invent a URL');
+ expect(readLinkTargets).toHaveBeenCalledWith(
+ expect.objectContaining({ draftId: DRAFT, ruleKeys: new Set(['faq']) }),
+ );
expect(draftUpdates()).toEqual([
{ status: 'in_review', agent_state: null, agent_state_at: expect.any(String) },
]);
diff --git a/supabase/migrations/00240_content_draft_suggestion_links.sql b/supabase/migrations/00240_content_draft_suggestion_links.sql
new file mode 100644
index 000000000..86a8cdd6e
--- /dev/null
+++ b/supabase/migrations/00240_content_draft_suggestion_links.sql
@@ -0,0 +1,27 @@
+-- ============================================================================
+-- 00240: the links on an agent's replace suggestion
+-- ============================================================================
+-- Content Agent rule gaps, A: the agent could never meet the Internal links,
+-- Outbound links or Cite sources inline rules, because a replace's new words
+-- were plain text (00217) and it had nowhere to link to. The server now gives
+-- it the brand's own pages and the draft's sources, and keeps a link only to
+-- one of those URLs.
+--
+-- A replace's after_text stays plain text: the editor finds an accepted one
+-- again by its words. Its links sit beside it, each the words from start to
+-- end (offsets into after_text) linked to href, and the editor puts them on
+-- as link marks when the suggestion is accepted. An insert keeps its links in
+-- its HTML, as its other blocks.
+alter table public.content_draft_suggestions
+ add column if not exists after_links jsonb
+ check (
+ after_links is null
+ or (
+ kind = 'replace'
+ and jsonb_typeof(after_links) = 'array'
+ and jsonb_array_length(after_links) between 1 and 20
+ )
+ );
+
+comment on column public.content_draft_suggestions.after_links is
+ 'A replace''s links: [{ "start", "end", "href" }], offsets into after_text (00240).';
diff --git a/supabase/schema.sql b/supabase/schema.sql
index f225db818..ef889c07c 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -35798,3 +35798,34 @@ $$;
revoke all on function public.health_probe(uuid, uuid, text, integer) from public, anon, authenticated;
grant execute on function public.health_probe(uuid, uuid, text, integer) to service_role;
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00240_content_draft_suggestion_links.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- ============================================================================
+-- 00240: the links on an agent's replace suggestion
+-- ============================================================================
+-- Content Agent rule gaps, A: the agent could never meet the Internal links,
+-- Outbound links or Cite sources inline rules, because a replace's new words
+-- were plain text (00217) and it had nowhere to link to. The server now gives
+-- it the brand's own pages and the draft's sources, and keeps a link only to
+-- one of those URLs.
+--
+-- A replace's after_text stays plain text: the editor finds an accepted one
+-- again by its words. Its links sit beside it, each the words from start to
+-- end (offsets into after_text) linked to href, and the editor puts them on
+-- as link marks when the suggestion is accepted. An insert keeps its links in
+-- its HTML, as its other blocks.
+alter table public.content_draft_suggestions
+ add column if not exists after_links jsonb
+ check (
+ after_links is null
+ or (
+ kind = 'replace'
+ and jsonb_typeof(after_links) = 'array'
+ and jsonb_array_length(after_links) between 1 and 20
+ )
+ );
+
+comment on column public.content_draft_suggestions.after_links is
+ 'A replace''s links: [{ "start", "end", "href" }], offsets into after_text (00240).';
+
diff --git a/web/messages/en.json b/web/messages/en.json
index 54fd1cefa..598dc2ebb 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -3610,6 +3610,7 @@
"locked": "AI quotes this passage, so agents don't change it.",
"stale": "The page changed here since the agent read it.",
"heading": "This would put more than a heading into the heading. Reject it, and add the text below the heading yourself.",
+ "links": "Links",
"acceptedToast": "{count, plural, one {Accepted} other {# changes accepted}} · undo any time",
"rejectedToast": "{count, plural, one {Rejected} other {# changes rejected}} · restore any time",
"undoneToast": "{count, plural, one {Undone · back to the suggestion} other {# undone · the suggestions are back}}",
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 196a9f6c0..39247a9e4 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
@@ -435,6 +435,7 @@ export function DraftEditor({
locked: t('suggestions.locked'),
stale: t('suggestions.stale'),
heading: t('suggestions.heading'),
+ links: t('suggestions.links'),
}),
[t],
);
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_suggestions.ts b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_suggestions.ts
index bd95af4ff..69c7f94a2 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_suggestions.ts
+++ b/web/src/app/[locale]/(dashboard)/dashboard/content/editor/[draftId]/_suggestions.ts
@@ -35,6 +35,8 @@ export interface SuggestionLabels {
locked: string;
stale: string;
heading: string;
+ /** "Links": before the addresses a suggestion links to. */
+ links: string;
}
interface SuggestionView {
@@ -243,6 +245,15 @@ export function acceptInto(
if (!placed) return false;
if (placed.at === 'words') {
tr.insertText(s.afterText, placed.from, placed.to);
+ // Its links (to the brand's pages and the draft's sources) on their words,
+ // and no other: a link the old words had doesn't spread over the new.
+ const link = state.schema.marks.link;
+ if (link && s.afterLinks?.length) {
+ tr.removeMark(placed.from, placed.from + s.afterText.length, link);
+ }
+ for (const { start, end, href } of link ? (s.afterLinks ?? []) : []) {
+ tr.addMark(placed.from + start, placed.from + end, link.create({ href }));
+ }
return true;
}
if (placed.at === 'gap') {
@@ -263,6 +274,11 @@ export function undoInto(
if (!placed) return false;
if (placed.at === 'added') {
tr.insertText(s.beforeText, placed.from, placed.to);
+ // Its links go with its words: the words back don't keep them.
+ const link = state.schema.marks.link;
+ if (link && s.afterLinks?.length) {
+ tr.removeMark(placed.from, placed.from + s.beforeText.length, link);
+ }
return true;
}
if (placed.at === 'blocks') {
@@ -319,6 +335,27 @@ function el<K extends keyof HTMLElementTagNameMap>(
return node;
}
+/** Linked words on a card: underlined, the address on hover. */
+const LINKED = 'underline decoration-dotted underline-offset-2';
+
+/** A replace's new words, its links underlined. */
+function linkedWords(s: DraftSuggestion): HTMLElement {
+ const ins = el(
+ 'ins',
+ 'rounded-sm bg-emerald-50 text-emerald-800 no-underline dark:bg-emerald-950/40 dark:text-emerald-300',
+ );
+ let at = 0;
+ for (const { start, end, href } of s.afterLinks ?? []) {
+ ins.append(document.createTextNode(s.afterText.slice(at, start)));
+ const linked = el('span', LINKED, s.afterText.slice(start, end));
+ linked.title = href;
+ ins.append(linked);
+ at = end;
+ }
+ ins.append(document.createTextNode(s.afterText.slice(at)));
+ return ins;
+}
+
function button(
className: string,
text: string,
@@ -401,11 +438,7 @@ function card(
s.beforeText,
),
document.createTextNode(' '),
- el(
- 'ins',
- 'rounded-sm bg-emerald-50 text-emerald-800 no-underline dark:bg-emerald-950/40 dark:text-emerald-300',
- s.afterText,
- ),
+ linkedWords(s),
);
} else {
const added = el(
@@ -413,9 +446,32 @@ function card(
'rounded-md bg-emerald-50 px-2 py-1 text-emerald-900 dark:bg-emerald-950/40 dark:text-emerald-200 [&_li]:ml-4 [&_li]:list-disc [&_p]:my-1',
);
added.innerHTML = cleanHtml(s.afterText, { keepImages: false }).html;
+ // Shown, not followed: a click on the card mustn't leave the editor.
+ for (const a of [...added.querySelectorAll('a')]) {
+ const span = el('span', LINKED, a.textContent ?? '');
+ span.title = a.getAttribute('href') ?? '';
+ a.replaceWith(span);
+ }
change.append(added);
}
box.append(change);
+ const hrefs = [
+ ...new Set(
+ s.kind === 'replace'
+ ? (s.afterLinks ?? []).map((l) => l.href)
+ : [...change.querySelectorAll<HTMLElement>('span[title]')].map((span) => span.title),
+ ),
+ ];
+ if (hrefs.length) {
+ // Where its links go, for the person to check before accepting.
+ box.append(
+ el(
+ 'p',
+ 'mt-1.5 truncate text-xs text-muted-foreground',
+ `${labels.links}: ${hrefs.join(' · ')}`,
+ ),
+ );
+ }
if (blocked) {
box.append(el('p', 'mt-1.5 text-xs text-amber-700 dark:text-amber-400', labels[blocked]));
}
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 a52e913be..05b2ce95f 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
@@ -958,6 +958,32 @@ describe('the content editor', () => {
expect(keepAgentBeforeVersion).toHaveBeenCalledTimes(1);
});
+ it('puts a replace’s links on its words, shows where they go, and takes them off on undo', async () => {
+ getContentDraft.mockResolvedValue(page);
+ getDraftSuggestions.mockResolvedValue([
+ suggestion({
+ afterText: 'Accuracy is shown per team, as our pricing page explains.',
+ afterLinks: [{ start: 35, end: 47, href: 'https://acme.example/pricing' }],
+ }),
+ ]);
+ await renderPage();
+
+ expect(cardOf('s1')!.textContent).toContain('Links: https://acme.example/pricing');
+ expect(cardOf('s1')!.querySelector('span[title]')!.textContent).toBe('pricing page');
+ await press('s1', 'Accept');
+ const html = () =>
+ (
+ container.querySelector('.ProseMirror') as HTMLElement & { editor: Editor }
+ ).editor.getHTML();
+ expect(html()).toMatch(
+ /<a [^>]*href="https:\/\/acme\.example\/pricing"[^>]*>pricing page<\/a>/,
+ );
+
+ await press('s1', 'Undo');
+ expect(pageText()).toContain(VAGUE);
+ expect(html()).not.toContain('<a ');
+ });
+
it('makes an accept again on the page when it changed while the decision was saved', async () => {
getContentDraft.mockResolvedValue(page);
getDraftSuggestions.mockResolvedValue(batch);
diff --git a/web/src/lib/actions/content-drafts.test.ts b/web/src/lib/actions/content-drafts.test.ts
index 01beebc03..8d118fffc 100644
--- a/web/src/lib/actions/content-drafts.test.ts
+++ b/web/src/lib/actions/content-drafts.test.ts
@@ -572,6 +572,7 @@ describe('agent suggestions', () => {
blockText: 'Our forecasting is very accurate.',
beforeText: 'very accurate',
afterText: 'shown per team',
+ afterLinks: null,
reason: 'answer a fan-out',
ruleKeys: ['dated'],
status: 'open',
@@ -579,6 +580,20 @@ describe('agent suggestions', () => {
expect(calls[0].filters).toContainEqual(['eq', 'draft_id', DRAFT]);
});
+ it('reads a replace’s links, keeping only safe ones inside its words (00240)', async () => {
+ list = [
+ row({
+ after_links: [
+ { start: 0, end: 5, href: 'https://acme.example/pricing' },
+ { start: 3, end: 9, href: 'https://acme.example/overlap' },
+ { start: 10, end: 14, href: 'javascript:alert(1)' },
+ ],
+ }),
+ ];
+ const [read] = await getDraftSuggestions(DRAFT);
+ expect(read.afterLinks).toEqual([{ start: 0, end: 5, href: 'https://acme.example/pricing' }]);
+ });
+
it('keeps who decided through the database function', async () => {
rpcResult = { data: 2, error: null };
await expect(decideDraftSuggestions([DRAFT, DRAFT], 'accepted')).resolves.toBe(2);
diff --git a/web/src/lib/actions/content-drafts.ts b/web/src/lib/actions/content-drafts.ts
index 952360c28..2c911ea07 100644
--- a/web/src/lib/actions/content-drafts.ts
+++ b/web/src/lib/actions/content-drafts.ts
@@ -61,6 +61,7 @@ import {
import {
MAX_DECIDE,
SUGGESTION_STATUSES,
+ suggestionLinks,
type DraftSuggestion,
type SuggestionStatus,
} from '@/lib/content/suggestions';
@@ -1341,7 +1342,7 @@ export async function getDraftSuggestions(id: string): Promise<DraftSuggestion[]
const { data, error } = await supabase
.from('content_draft_suggestions')
.select(
- 'id, batch_id, action_id, kind, block_text, before_text, after_text, reason, rule_keys, position, status, created_at, actions(action_no)',
+ 'id, batch_id, action_id, kind, block_text, before_text, after_text, after_links, reason, rule_keys, position, status, created_at, actions(action_no)',
)
.eq('draft_id', id)
.order('created_at', { ascending: false })
@@ -1366,6 +1367,7 @@ export async function getDraftSuggestions(id: string): Promise<DraftSuggestion[]
blockText: row.block_text,
beforeText: row.before_text,
afterText: row.after_text,
+ afterLinks: row.kind === 'insert' ? null : suggestionLinks(row.after_links, row.after_text),
reason: row.reason,
ruleKeys: row.rule_keys ?? [],
status: row.status as SuggestionStatus,
diff --git a/web/src/lib/content/suggestions.test.ts b/web/src/lib/content/suggestions.test.ts
index c0ba8b278..e5ea6b5f4 100644
--- a/web/src/lib/content/suggestions.test.ts
+++ b/web/src/lib/content/suggestions.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { growsPastLimit, headingLimit } from './suggestions';
+import { growsPastLimit, headingLimit, suggestionLinks } from './suggestions';
/**
* How long an agent's change may make a heading: an H1 up to 70 characters,
@@ -21,3 +21,30 @@ describe('growsPastLimit', () => {
expect(growsPastLimit(2, 120, 121)).toBe(true);
});
});
+
+/** A replace's links (00240), as the editor may put them on. */
+describe('suggestionLinks', () => {
+ it('keeps safe links inside the words, in order, not overlapping', () => {
+ expect(
+ suggestionLinks(
+ [
+ { start: 4, end: 13, href: 'https://acme.example/pricing' },
+ { start: 10, end: 20, href: 'https://acme.example/overlap' },
+ { start: 14, end: 18, href: '/guides/brew' },
+ { start: 19, end: 99, href: 'https://past.example' },
+ { start: 20, end: 21, href: 'javascript:alert(1)' },
+ ],
+ 'See our plans for teams.',
+ ),
+ ).toEqual([
+ { start: 4, end: 13, href: 'https://acme.example/pricing' },
+ { start: 14, end: 18, href: '/guides/brew' },
+ ]);
+ });
+
+ it('is null without any', () => {
+ expect(suggestionLinks(null, 'x')).toBeNull();
+ expect(suggestionLinks([], 'x')).toBeNull();
+ expect(suggestionLinks([{ start: 0, end: 1 }], 'x')).toBeNull();
+ });
+});
diff --git a/web/src/lib/content/suggestions.ts b/web/src/lib/content/suggestions.ts
index e083c5ffc..ae3d788f9 100644
--- a/web/src/lib/content/suggestions.ts
+++ b/web/src/lib/content/suggestions.ts
@@ -8,6 +8,8 @@
* text, as the agent read it.
*/
+import { safeLinkHref } from './editor';
+
export const SUGGESTION_STATUSES = ['open', 'accepted', 'rejected'] as const;
export type SuggestionStatus = (typeof SUGGESTION_STATUSES)[number];
@@ -24,6 +26,8 @@ export interface DraftSuggestion {
beforeText: string;
/** replace: the new words; insert: the blocks added, as HTML. */
afterText: string;
+ /** replace: the links on the new words (00240); an insert's are in its HTML. */
+ afterLinks?: SuggestionLink[] | null;
/** Why, as the agent says it: "add a dated data point (rule)". */
reason: string;
/** The rules it is meant to fix. */
@@ -53,6 +57,31 @@ export function growsPastLimit(level: number, now: number, then: number): boolea
return then > headingLimit(level) && then > now;
}
+/** A link on a replace's new words: afterText from start to end, linked to href. */
+export interface SuggestionLink {
+ start: number;
+ end: number;
+ href: string;
+}
+
+/**
+ * A replace's stored links (after_links, 00240) as the editor may put them
+ * on: in order, inside the words, not overlapping, each a safe link. Null
+ * when there are none.
+ */
+export function suggestionLinks(raw: unknown, afterText: string): SuggestionLink[] | null {
+ if (!Array.isArray(raw)) return null;
+ const links: SuggestionLink[] = [];
+ for (const item of raw as Partial<SuggestionLink>[]) {
+ const { start, end } = item ?? {};
+ const href = typeof item?.href === 'string' ? safeLinkHref(item.href) : null;
+ if (!href || !Number.isInteger(start) || !Number.isInteger(end)) continue;
+ if (start! < (links.at(-1)?.end ?? 0) || end! <= start! || end! > afterText.length) continue;
+ links.push({ start: start!, end: end!, href });
+ }
+ return links.length ? links : null;
+}
+
/** The most suggestions decided at once (00217). */
export const MAX_DECIDE = 200;
diff --git a/web/src/types/supabase.ts b/web/src/types/supabase.ts
index 09e2b78e9..443d5f186 100644
--- a/web/src/types/supabase.ts
+++ b/web/src/types/supabase.ts
@@ -1083,6 +1083,7 @@ export type Database = {
content_draft_suggestions: {
Row: {
action_id: string | null
+ after_links: Json | null
after_text: string
agent: string
batch_id: string
@@ -1101,6 +1102,7 @@ export type Database = {
}
Insert: {
action_id?: string | null
+ after_links?: Json | null
after_text: string
agent?: string
batch_id: string
@@ -1119,6 +1121,7 @@ export type Database = {
}
Update: {
action_id?: string | null
+ after_links?: Json | null
after_text?: string
agent?: string
batch_id?: string