fix(agent): bound generated research queries (#165)

## Why

Production QA of the canonical Markdown research PDF flow exposed a
mismatch between accepted research topics and generated provider
queries. A valid detailed topic could exceed the narrower
generated-query schema once an angle suffix was appended, causing
`research_deep` to fail validation and the agent to fall back to manual
research.

## What changed

- align generated research queries with the provider's 2,000-character
query boundary
- preserve every distinct research angle when a long topic must be
shortened
- apply the same safe composition to fan-out goals and entity queries
- clarify that tool-generated topics should remain concise and focused

## Architecture and migration impact

No database, deployment-topology, or public API changes. This is an
internal agent workflow validation fix.

## Verification

- `pnpm lint`
- `pnpm typecheck`
- `pnpm turbo build --force`
- `pnpm deadcode`
- `pnpm architecture:check`
- `pnpm turbo skills:build`
- targeted 2,000-character deep-research and fan-out query boundary
exercise, including distinct-angle and suffix-preservation assertions
- production natural-language research flow will be rerun after
merge/deploy

The local machine reports the existing Node engine warning (repo pins
24.18.0; local Node is 26.4.0); all checks completed successfully.

Author: iamjr15

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

@@ -41,7 +41,7 @@ export const ResearchReportSchema = z.strictObject({
 });
 
 export const ResearchQuerySchema = z.strictObject({
-  query: z.string().trim().min(1).max(1_000),
+  query: z.string().trim().min(1).max(2_000),
 });
 
 export const DeepResearchInputSchema = z.strictObject({
@@ -54,7 +54,14 @@ export const DeepResearchInputSchema = z.strictObject({
     .describe(
       "Focused research pass count: use 3 for a concise or narrow report, 4 by default, and 5-6 only when the user explicitly asks for deeper coverage.",
     ),
-  topic: z.string().trim().min(1).max(2_000),
+  topic: z
+    .string()
+    .trim()
+    .min(1)
+    .max(2_000)
+    .describe(
+      "Concise research topic and requested report focus. Preserve the user's requirements without adding unrelated detail.",
+    ),
 });
 
 export const DeepResearchFanoutInputSchema = z.strictObject({

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

@@ -1,17 +1,19 @@
+const MAX_RESEARCH_QUERY_CHARACTERS = 2_000;
+
 export function buildDeepResearchQueries(
   topic: string,
   maxQueries: number,
 ): Array<{ query: string }> {
   const trimmedTopic = topic.trim();
-  const templates = [
-    `${trimmedTopic} current landscape overview and authoritative primary sources`,
-    `${trimmedTopic} technical product and implementation details constraints`,
-    `${trimmedTopic} risks limitations failure modes criticism`,
-    `${trimmedTopic} evidence data benchmarks case studies adoption`,
-    `${trimmedTopic} legal regulatory economic and operational considerations`,
-    `${trimmedTopic} recent developments future trends disagreements open questions`,
+  const angles = [
+    "current landscape overview and authoritative primary sources",
+    "technical product and implementation details constraints",
+    "risks limitations failure modes criticism",
+    "evidence data benchmarks case studies adoption",
+    "legal regulatory economic and operational considerations",
+    "recent developments future trends disagreements open questions",
   ];
-  return dedupeQueries(templates)
+  return dedupeQueries(angles.map((angle) => buildResearchQuery(trimmedTopic, angle)))
     .slice(0, maxQueries)
     .map((query) => ({ query }));
 }
@@ -24,27 +26,40 @@ export function buildFanoutQueries(input: {
   const goal = input.goal.trim();
   if (input.entities && input.entities.length > 0) {
     return input.entities.slice(0, input.maxQueries).map((entity) => ({
-      query: `${goal}: ${entity}`,
+      query: buildResearchQuery(goal, entity, ": "),
     }));
   }
 
-  const templates = [
-    `${goal} top entities overview`,
-    `${goal} company and competitor landscape`,
-    `${goal} pricing and packaging comparison`,
-    `${goal} recent news and announcements`,
-    `${goal} customer segments and use cases`,
-    `${goal} product capabilities matrix`,
-    `${goal} funding traction hiring signals`,
-    `${goal} strengths weaknesses opportunities threats`,
-    `${goal} market size and growth estimates`,
-    `${goal} risks and open questions`,
+  const angles = [
+    "top entities overview",
+    "company and competitor landscape",
+    "pricing and packaging comparison",
+    "recent news and announcements",
+    "customer segments and use cases",
+    "product capabilities matrix",
+    "funding traction hiring signals",
+    "strengths weaknesses opportunities threats",
+    "market size and growth estimates",
+    "risks and open questions",
   ];
-  return dedupeQueries(templates)
+  return dedupeQueries(angles.map((angle) => buildResearchQuery(goal, angle)))
     .slice(0, input.maxQueries)
     .map((query) => ({ query }));
 }
 
+function buildResearchQuery(subject: string, qualifier: string, separator = " "): string {
+  const suffix = `${separator}${qualifier}`;
+  const maxSubjectCharacters = MAX_RESEARCH_QUERY_CHARACTERS - suffix.length;
+  if (subject.length <= maxSubjectCharacters) {
+    return `${subject}${suffix}`;
+  }
+  const candidate = subject.slice(0, maxSubjectCharacters - 1).trimEnd();
+  const wordBoundary = candidate.lastIndexOf(" ");
+  const bounded =
+    wordBoundary >= maxSubjectCharacters * 0.75 ? candidate.slice(0, wordBoundary) : candidate;
+  return `${bounded.trimEnd()}…${suffix}`;
+}
+
 function dedupeQueries(queries: string[]): string[] {
   const seen = new Set<string>();
   const deduped: string[] = [];