fix: reject incomplete research reports before publication (#177)

## Summary

- Rejects length-truncated or structurally invalid research Markdown
before any PDF is published.
- Restricts every citation to provider-collected HTTP(S) evidence and
requires the final Sources list to match inline citations exactly.
- Doubles synthesis output headroom so reasoning-capable models can
finish a focused report without cutting off the references.

## Architecture

The synthesis model still produces the canonical Markdown displayed in
chat and rendered into the PDF. A deterministic validation boundary now
runs before `ResearchReportSchema` succeeds and before the artifact
renderer or generated-output store is invoked. Invalid output uses the
existing bounded in-memory retry; a second invalid result fails safely
instead of publishing a broken report.

## Decisions Made

| Decision | Choice | Alternatives considered | Reasoning |
|---|---|---|---|
| Failure handling | Reject and regenerate | Repair malformed Markdown
after generation | Repair would invent or alter source attribution and
make chat/PDF diverge from the canonical report. |
| Citation trust | Exact canonical URL membership | Accept any
syntactically valid link | Research reports must cite only evidence
returned by Exa or Firecrawl. |
| Sources contract | Exact set parity with inline citations | Allow
partial or extra references | Prevents missing, unused, duplicate, and
truncated source entries. |
| Output budget | 8,192 tokens with a 20,000-character report bound |
Keep the 4,096-token ceiling | Provides headroom for reasoning and long
URLs while retaining the existing byte bound and 1,200-word prompt. |

## Edge Cases Handled

| Scenario | Handling |
|---|---|
| Provider stops at output limit | Reject by finish reason and retry. |
| Markdown link is cut off | Reject the unparsed link token. |
| Model cites an uncollected URL | Reject before artifact generation. |
| Sources list omits or adds a citation | Reject unless source and body
URL sets are equal. |
| Duplicate or non-link source entry | Reject the report. |
| Wrong heading/list shape | Require one H1, one final H2 Sources
section, and an unordered link-only list. |

## How to Review

1. Start with `research-markdown.ts` for the deterministic publication
contract.
2. Review `deep-research-workflow.ts` for finish-reason wiring, output
headroom, and synthesis instructions.
3. Confirm `packages/agent-core/README.md` matches the runtime boundary.

## Verification

- `pnpm lint`
- `pnpm typecheck`
- `pnpm turbo build --force`
- `pnpm deadcode`
- `pnpm architecture:check`
- `pnpm turbo skills:build`
- Direct contract exercise: one valid report accepted unchanged; length
cutoff, malformed source, uncollected URL, missing source entry,
body/source mismatch, and ordered Sources list all rejected.
- Production baseline reproduced before this change: natural-language
research completed, PDF downloaded as a valid 4-page A4 document, and
`/` listed it; visual inspection exposed the truncated final Markdown
link this PR prevents.

Author: iamjr15

packages/agent-core/README.md

@@ -78,10 +78,12 @@ Each concurrent research pass performs one bounded Exa discovery call and an opt
 Firecrawl extraction of its primary result. Provider-owned IDs, URLs, excerpts, and
 the durable claim map are assembled deterministically instead of asking a model to
 reproduce citation identifiers. The sole tool-free model call writes only the canonical
-Markdown report from those byte-bounded evidence packs. It has an operational timeout
-and one in-memory retry for transient provider or invalid Markdown failures; request
-cancellation always wins and no secret-bearing state is snapshotted. Prose URL scraping
-is not an accepted provenance boundary.
+Markdown report from those byte-bounded evidence packs. Before publication, the workflow
+rejects truncated generations and validates the heading structure, citation URLs, and the
+one-to-one relationship between inline citations and the final Sources list. It has an
+operational timeout and one in-memory retry for transient provider or invalid Markdown
+failures; request cancellation always wins and no secret-bearing state is snapshotted.
+Prose URL scraping is not an accepted provenance boundary.
 Successful top-level deep-research and fan-out tools render the validated report's
 canonical GitHub-flavored Markdown directly into a PDF artifact. The chat response
 and PDF therefore preserve the same headings, prose, lists, tables, links, citations,

packages/agent-core/src/mastra/workflows/deep-research-workflow.ts

@@ -7,6 +7,7 @@ import {
   ResearchRuntimeContextSchema,
 } from "../../tools/research";
 import { CONTEXT } from "../context";
+import { parseResearchMarkdown } from "./research-markdown";
 import {
   exaSource,
   firecrawlSource,
@@ -30,10 +31,9 @@ const RESEARCH_RESULT_TEXT_CHARACTERS = 1_600;
 const RESEARCH_EVIDENCE_CHARACTERS_PER_SOURCE = 3_000;
 const RESEARCH_SYNTHESIS_EVIDENCE_CHARACTERS_PER_SOURCE = 1_200;
 const RESEARCH_SCRAPE_CHARACTERS = 6_000;
-const RESEARCH_SYNTHESIS_MAX_OUTPUT_TOKENS = 4_096;
+const RESEARCH_SYNTHESIS_MAX_OUTPUT_TOKENS = 8_192;
 const RESEARCH_MODEL_TIMEOUT_MS = 75_000;
 const RESEARCH_MODEL_ATTEMPTS = 2;
-const ResearchMarkdownSchema = z.string().trim().min(1).max(20_000).startsWith("# ");
 
 interface ResearchEvidenceSource {
   content: string;
@@ -160,7 +160,11 @@ function createSynthesisStep(id: string, config: ResearchWorkflowPrompts) {
         return ResearchReportSchema.parse({
           claims,
           findings: inputData,
-          report: parseResearchMarkdown(response.text),
+          report: parseResearchMarkdown({
+            finishReason: response.finishReason,
+            sources,
+            value: response.text,
+          }),
           sources,
         });
       });
@@ -259,7 +263,8 @@ function researchSynthesisPrompt(config: ResearchWorkflowPrompts, evidence: unkn
     "Start with one level-one heading. The returned Markdown is displayed unchanged in chat and rendered unchanged into the PDF.",
     "Keep the report focused and complete within 1,200 words while retaining actionable findings and citations.",
     "Write report as polished GitHub-flavored Markdown for direct display and PDF rendering. Preserve a clear heading hierarchy, lists, and comparison tables where useful.",
-    "Cite factual claims with descriptive Markdown links to the exact source URLs in the evidence, and finish with a Sources heading containing only sources used in the report.",
+    "Cite factual claims with descriptive Markdown links to the exact source URLs in the evidence.",
+    "Finish with exactly one level-two Sources heading. Under it, include one bullet per cited URL, formatted only as a descriptive Markdown link. Every inline citation must appear in that list, and every listed source must be cited inline.",
   ].join("\n");
 }
 
@@ -303,19 +308,6 @@ function compactEvidence(value: string): string {
     .slice(0, RESEARCH_SYNTHESIS_EVIDENCE_CHARACTERS_PER_SOURCE);
 }
 
-function parseResearchMarkdown(value: unknown): string {
-  const parsed = ResearchMarkdownSchema.safeParse(value);
-  if (parsed.success) {
-    return parsed.data;
-  }
-  throw new APIError(
-    502,
-    "upstream_provider_outage",
-    "Research synthesis returned invalid Markdown",
-    { retriable: true },
-  );
-}
-
 async function generateResearchOutput<T>(
   abortSignal: AbortSignal,
   generate: (generationSignal: AbortSignal) => Promise<T>,

packages/agent-core/src/mastra/workflows/research-markdown.ts

@@ -0,0 +1,211 @@
+import { APIError } from "@cheatcode/observability";
+import { lexer, type Token, type Tokens } from "marked";
+import { z } from "zod/v4";
+import type { ResearchSource } from "./research-schemas";
+
+const ResearchMarkdownSchema = z.string().trim().min(1).max(20_000).startsWith("# ");
+const REJECTED_FINISH_REASONS = new Set(["content-filter", "error", "length", "tool-calls"]);
+
+interface ParseResearchMarkdownOptions {
+  finishReason: string | undefined;
+  sources: ResearchSource[];
+  value: unknown;
+}
+
+/** Validates the complete, evidence-bound Markdown contract before artifact publication. */
+export function parseResearchMarkdown(options: ParseResearchMarkdownOptions): string {
+  if (options.finishReason && REJECTED_FINISH_REASONS.has(options.finishReason)) {
+    throw invalidResearchMarkdown();
+  }
+  const parsed = ResearchMarkdownSchema.safeParse(options.value);
+  if (!parsed.success) {
+    throw invalidResearchMarkdown();
+  }
+  const tokens = lexer(parsed.data, { gfm: true });
+  validateHeadingStructure(tokens);
+  validateCitationStructure(tokens, options.sources);
+  return parsed.data;
+}
+
+function validateHeadingStructure(tokens: Token[]): void {
+  const meaningfulTokens = tokens.filter((token) => token.type !== "space");
+  const first = meaningfulTokens[0];
+  const levelOneHeadings = meaningfulTokens.filter(
+    (token) => isHeadingToken(token) && token.depth === 1,
+  );
+  if (!first || !isHeadingToken(first) || first.depth !== 1 || levelOneHeadings.length !== 1) {
+    throw invalidResearchMarkdown();
+  }
+}
+
+function validateCitationStructure(tokens: Token[], sources: ResearchSource[]): void {
+  const sourceHeadingIndexes = tokens.flatMap((token, index) =>
+    isHeadingToken(token) && token.depth === 2 && token.text.trim().toLowerCase() === "sources"
+      ? [index]
+      : [],
+  );
+  if (sourceHeadingIndexes.length !== 1) {
+    throw invalidResearchMarkdown();
+  }
+  const sourceHeadingIndex = sourceHeadingIndexes[0];
+  if (sourceHeadingIndex === undefined) {
+    throw invalidResearchMarkdown();
+  }
+  const sourceBlocks = tokens
+    .slice(sourceHeadingIndex + 1)
+    .filter((token) => token.type !== "space");
+  const sourceList = sourceBlocks[0];
+  if (
+    sourceBlocks.length !== 1 ||
+    !isListToken(sourceList) ||
+    sourceList.ordered ||
+    sourceList.items.length === 0 ||
+    containsUnparsedMarkdownLink(tokens)
+  ) {
+    throw invalidResearchMarkdown();
+  }
+
+  const allowedUrls = new Set(sources.map((source) => canonicalHttpUrl(source.url)));
+  const bodyUrls = validateAllowedLinks(tokens.slice(0, sourceHeadingIndex), allowedUrls);
+  const listedUrls = validateSourceList(sourceList, allowedUrls);
+  if (bodyUrls.size === 0 || !setsEqual(bodyUrls, listedUrls)) {
+    throw invalidResearchMarkdown();
+  }
+}
+
+function validateAllowedLinks(tokens: Token[], allowedUrls: Set<string>): Set<string> {
+  const urls = new Set<string>();
+  for (const link of collectLinks(tokens)) {
+    const url = canonicalHttpUrl(link.href);
+    if (!allowedUrls.has(url)) {
+      throw invalidResearchMarkdown();
+    }
+    urls.add(url);
+  }
+  return urls;
+}
+
+function validateSourceList(sourceList: Tokens.List, allowedUrls: Set<string>): Set<string> {
+  const urls = new Set<string>();
+  for (const item of sourceList.items) {
+    const links = collectLinks(item.tokens);
+    if (links.length !== 1 || textOutsideLinks(item.tokens).trim()) {
+      throw invalidResearchMarkdown();
+    }
+    const url = canonicalHttpUrl(links[0]?.href);
+    if (!allowedUrls.has(url) || urls.has(url)) {
+      throw invalidResearchMarkdown();
+    }
+    urls.add(url);
+  }
+  return urls;
+}
+
+function collectLinks(tokens: Token[]): Tokens.Link[] {
+  const links: Tokens.Link[] = [];
+  for (const token of tokens) {
+    if (isLinkToken(token)) {
+      links.push(token);
+      continue;
+    }
+    const children = childTokens(token);
+    if (children.length > 0) {
+      links.push(...collectLinks(children));
+    }
+  }
+  return links;
+}
+
+function textOutsideLinks(tokens: Token[]): string {
+  return tokens
+    .map((token) => {
+      if (token.type === "link" || token.type === "space") {
+        return "";
+      }
+      const children = childTokens(token);
+      if (children.length > 0) {
+        return textOutsideLinks(children);
+      }
+      return "text" in token && typeof token.text === "string" ? token.text : "";
+    })
+    .join("");
+}
+
+function containsUnparsedMarkdownLink(tokens: Token[]): boolean {
+  return tokens.some((token) => {
+    if (isLinkToken(token) || token.type === "code" || token.type === "codespan") {
+      return false;
+    }
+    const children = childTokens(token);
+    if (children.length > 0) {
+      return containsUnparsedMarkdownLink(children);
+    }
+    return (
+      "text" in token &&
+      typeof token.text === "string" &&
+      /!?\[[^\]\n]+\]\([^)\n]*(?:\n|$)/u.test(token.text)
+    );
+  });
+}
+
+function childTokens(token: Token): Token[] {
+  if ("tokens" in token && Array.isArray(token.tokens)) {
+    return token.tokens;
+  }
+  if (isListToken(token)) {
+    return token.items.flatMap((item) => item.tokens);
+  }
+  if (isTableToken(token)) {
+    return [
+      ...token.header.flatMap((cell) => cell.tokens),
+      ...token.rows.flatMap((row) => row.flatMap((cell) => cell.tokens)),
+    ];
+  }
+  return [];
+}
+
+function isHeadingToken(token: Token): token is Tokens.Heading {
+  return token.type === "heading" && "depth" in token && typeof token.depth === "number";
+}
+
+function isLinkToken(token: Token): token is Tokens.Link {
+  return token.type === "link" && "href" in token && typeof token.href === "string";
+}
+
+function isListToken(token: Token | undefined): token is Tokens.List {
+  return Boolean(token && token.type === "list" && "items" in token && Array.isArray(token.items));
+}
+
+function isTableToken(token: Token): token is Tokens.Table {
+  return token.type === "table" && "rows" in token && Array.isArray(token.rows);
+}
+
+function canonicalHttpUrl(value: string | undefined): string {
+  try {
+    const url = new URL(value ?? "");
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw invalidResearchMarkdown();
+    }
+    return url.href;
+  } catch (error) {
+    if (error instanceof APIError) {
+      throw error;
+    }
+    throw invalidResearchMarkdown();
+  }
+}
+
+function setsEqual(left: Set<string>, right: Set<string>): boolean {
+  return left.size === right.size && [...left].every((value) => right.has(value));
+}
+
+function invalidResearchMarkdown(): APIError {
+  return new APIError(
+    502,
+    "upstream_provider_outage",
+    "Research synthesis returned invalid Markdown",
+    {
+      retriable: true,
+    },
+  );
+}