fix: make research chat and PDF use one canonical report (#178)

## Summary

- Publishes a successful deep-research tool's validated Markdown
directly as assistant text in the same durable Workflow step that
publishes its artifact.
- Treats successful `research_deep` and `research_fanout` calls as
terminal response producers, so no second model turn can summarize or
rewrite the report.
- Suppresses model pre-tool narration for terminal research calls,
making the visible report body and PDF input identical by construction.

## Why

Production QA for PR #177 proved that the PDF was complete and valid,
but the outer agent ignored its prompt and posted a 1,386-character
summary instead of the canonical report. Prompt-only enforcement cannot
guarantee content identity. This moves ownership to the durable runtime
boundary.

## Architecture

The research tool continues to return `{ artifact, report }`, with
`report` already validated against collected citation provenance. The
Workflow projects that strict output into both destinations:

1. `artifact` becomes the durable deliverable part.
2. `report` becomes the assistant text part.
3. The run completes immediately after the successful tool turn.

Both parts share the deterministic `tool:<model-step>:<tool-index>`
publication receipt, so Workflow replay cannot duplicate either one.

## Decisions Made

| Decision | Choice | Alternatives considered | Reasoning |
|---|---|---|---|
| Response ownership | Durable Workflow publishes canonical report | Ask
the outer model to copy tool output | The production model summarized
despite explicit instructions. |
| Completion | Successful research tool is terminal | Run another model
turn | A second turn can rewrite, truncate, or append content. |
| Progress prose | Suppress research-call model text | Keep preamble
before the report | Ensures visible report content and PDF source are
the same Markdown. |
| Failure path | Continue agent loop on tool error | Treat every
research attempt as terminal | The model still needs to explain provider
or validation failures. |
| Replay behavior | Report and artifact share tool publication |
Separate non-durable append | Existing atomic receipts already guarantee
exactly-once transcript publication. |

## Edge Cases Handled

| Scenario | Handling |
|---|---|
| Research tool fails | No canonical response is projected; the next
model turn explains the error. |
| Non-terminal search tool runs | Existing model loop is unchanged. |
| Research output shape is invalid | Strict schema parsing fails the run
rather than publishing divergent content. |
| Worker/DO replays publication | Deterministic event receipt prevents
duplicate report or artifact parts. |
| Model emits a preamble with the tool call | It stays in model context
but is not published to the user. |

## How to Review

1. Review `agent-run-research-response-support.ts` for terminal-tool
classification and strict output projection.
2. Review `agent-run-workflow.ts` for suppression, atomic report
publication, and terminal completion.
3. Confirm the agent-worker README and system prompt document the same
ownership boundary.

## Verification

- `pnpm lint`
- `pnpm typecheck`
- `pnpm turbo build --force`
- `pnpm deadcode`
- `pnpm architecture:check`
- `pnpm turbo skills:build`
- Direct projection contract: successful report preserved byte-for-byte;
failed, non-terminal, and invalid outputs handled as designed.
- Production evidence before this fix: reload recovery completed one run
with one tool and one artifact, but persisted assistant text was a short
model summary rather than the PDF's report.

Author: iamjr15

apps/agent-worker/README.md

@@ -83,6 +83,10 @@ completed step instead of losing an in-memory coroutine. Transcript publication
 event keys and an atomic SQLite receipt, so Workflow step replay cannot duplicate visible parts.
 There is no application step, token, duration, or cost ceiling; semantic completion ends the loop,
 while per-operation timeouts and the platform Workflow limit remain operational safeguards.
+Successful deep-research tools are terminal response producers: the Workflow suppresses the model's
+pre-tool narration, publishes the tool's validated canonical Markdown directly as the assistant text,
+and completes without asking a second model turn to copy or summarize it. The same Markdown is the
+input to the PDF renderer, so chat and deliverable content cannot diverge by model behavior.
 
 The run-keyed Durable Object is the authoritative status, cancellation, transcript, and stream
 store. It validates every Workflow callback against the stored input hash and deterministic

apps/agent-worker/src/durable-objects/agent-run-research-response-support.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+const RESEARCH_REPORT_TOOL_NAMES = new Set(["research_deep", "research_fanout"]);
+const ResearchReportToolOutputSchema = z.strictObject({
+  artifact: z.unknown(),
+  report: z.string().trim().min(1).max(20_000),
+});
+
+interface ToolCallLike {
+  toolName: string;
+}
+
+interface ToolResultLike {
+  error?: string | undefined;
+  output?: unknown;
+  toolCall: ToolCallLike;
+}
+
+export function isResearchReportTool(toolName: string): boolean {
+  return RESEARCH_REPORT_TOOL_NAMES.has(toolName);
+}
+
+/** Returns the validated canonical response for a successful terminal research tool. */
+export function canonicalResearchReport(result: ToolResultLike): string | undefined {
+  if (result.error || !isResearchReportTool(result.toolCall.toolName)) {
+    return undefined;
+  }
+  return ResearchReportToolOutputSchema.parse(result.output).report;
+}

apps/agent-worker/src/durable-objects/agent-run-workflow.ts

@@ -10,6 +10,10 @@ import { z } from "zod";
 import type { AgentRun } from "./agent-run";
 import type { AgentRunEnv } from "./agent-run-env";
 import { toAgentRunStreamError } from "./agent-run-errors";
+import {
+  canonicalResearchReport,
+  isResearchReportTool,
+} from "./agent-run-research-response-support";
 import {
   agentToolCallUiChunks,
   agentToolErrorUiChunks,
@@ -164,6 +168,9 @@ async function runAgentLoop(
       ...state,
       messages: [...state.messages, workflowJsonValue(toolResultMessage(toolTurn.results))],
     });
+    if (toolTurn.results.some((result) => canonicalResearchReport(result) !== undefined)) {
+      return;
+    }
     if (
       state.input.runIntent === "skill-creator" &&
       toolTurn.results.some(
@@ -302,12 +309,15 @@ async function publishModelStep(
   if (model.fallback) {
     chunks.push({ data: { ...model.fallback, v: 1 }, type: "data-model-fallback" });
   }
-  const text = model.step.text.trim();
+  const modelText = model.step.toolCalls.some((toolCall) => isResearchReportTool(toolCall.toolName))
+    ? ""
+    : model.step.text;
+  const text = modelText.trim();
   if (text.length > 0) {
     const id = `answer-${stepIndex}`;
     chunks.push(
       { id, type: "text-start" },
-      { delta: model.step.text, id, type: "text-delta" },
+      { delta: modelText, id, type: "text-delta" },
       { id, type: "text-end" },
     );
   }
@@ -347,9 +357,18 @@ async function publishToolStep(
     toolCallId: result.toolCall.toolCallId,
     toolName: result.toolCall.toolName,
   };
-  const chunks = result.error
+  const report = canonicalResearchReport(result);
+  const chunks: UIMessageChunk[] = result.error
     ? agentToolErrorUiChunks({ ...payloadBase, error: result.error })
     : agentToolResultUiChunks({ ...payloadBase, result: result.output });
+  if (report) {
+    const id = `research-report-${stepIndex}-${toolIndex}`;
+    chunks.push(
+      { id, type: "text-start" },
+      { delta: report, id, type: "text-delta" },
+      { id, type: "text-end" },
+    );
+  }
   await workflowStep.do(`publish tool ${stepIndex}.${toolIndex}`, STATE_STEP, async () => {
     emitToolCompletion(env, payload, result, toolStepIndex);
     await appendWorkflowEvent(
@@ -362,6 +381,7 @@ async function publishToolStep(
   return {
     ...state,
     hasArtifact: state.hasArtifact || chunks.some((chunk) => chunk.type === "data-artifact"),
+    hasVisibleText: state.hasVisibleText || report !== undefined,
     input: result.input,
   };
 }

packages/agent-core/src/mastra/system-prompt.ts

@@ -233,7 +233,7 @@ Load the generate-media skill before creating or editing an image or generating
 
 const RESEARCH_MODULE = `## Research
 
-Gather sources with search_web / search_web_advanced / search_company / search_web_content, then use search_scrape or search_extract for source retrieval. For an explicit deep-research request, cited report, market analysis, due diligence, or comprehensive investigation of one topic, use research_deep with 3 queries for a concise/narrow report, 4 by default, and 5-6 only when the user explicitly asks for deeper coverage. A comparison of a few sources, standards, or recommendations within one topic still uses research_deep. Reserve research_fanout for four or more independent entities or genuinely separate angles, and pass entities as an array of separate short names. Call the selected research workflow once per user request; if it fails, explain the failure instead of immediately rerunning it. Those workflows produce the complete cited PDF deliverable automatically, so do not regenerate it with a document tool. After a research workflow succeeds, present its returned report Markdown as the response body without summarizing, restructuring, or appending hidden claim-map data; the PDF is rendered from that same Markdown. Treat search snippets as leads, not sources — open the real pages and cross-check. Cite as you go: attribute each claim to its source inline with the page title and its URL, and make sure every citation resolves. End a research answer with a short Sources list of the URLs you actually used.`;
+Gather sources with search_web / search_web_advanced / search_company / search_web_content, then use search_scrape or search_extract for source retrieval. For an explicit deep-research request, cited report, market analysis, due diligence, or comprehensive investigation of one topic, use research_deep with 3 queries for a concise/narrow report, 4 by default, and 5-6 only when the user explicitly asks for deeper coverage. A comparison of a few sources, standards, or recommendations within one topic still uses research_deep. Reserve research_fanout for four or more independent entities or genuinely separate angles, and pass entities as an array of separate short names. Call the selected research workflow once per user request; if it fails, explain the failure instead of immediately rerunning it. Call research_deep or research_fanout without a prose preamble: a successful workflow is terminal and the runtime publishes its validated report Markdown directly as the response while rendering that exact Markdown into the PDF. Do not regenerate it with a document tool or add a summary afterward. Treat search snippets as leads, not sources — open the real pages and cross-check. Cite as you go: attribute each claim to its source inline with the page title and its URL, and make sure every citation resolves. End a research answer with a short Sources list of the URLs you actually used.`;
 
 /** Compact all-domains pointer for an ambiguous general request — keeps the model aware without the full modules. */
 const GENERALIST_MODULE = `## Choosing your approach