@moxxy/mode-deep-research 0.26.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@moxxy/mode-deep-research",
+  "version": "0.26.0",
+  "description": "Deep-research loop strategy for moxxy: decompose the user question into parallel sub-queries, fan out via subagents, synthesize a cited writeup.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "mode",
+    "research",
+    "fan-out"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/mode-deep-research"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "mode"
+    },
+    "requirements": [
+      {
+        "kind": "plugin",
+        "name": "@moxxy/plugin-subagents",
+        "state": "registered",
+        "hint": "Enable @moxxy/plugin-subagents — deep-research fans out sub-queries via ctx.subagents."
+      }
+    ]
+  },
+  "dependencies": {
+    "@moxxy/sdk": "0.26.0",
+    "@moxxy/plugin-subagents": "0.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^3.24.0",
+    "@moxxy/testing": "0.0.44",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/core": "0.26.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/approval.test.ts

@@ -0,0 +1,82 @@
+import type { ApprovalDecision, ApprovalRequest, ModeContext } from '@moxxy/sdk';
+import { describe, expect, it, vi } from 'vitest';
+
+import { runQueryApprovalGate, runSynthesisApprovalGate } from './approval.js';
+import { MAX_REDRAFTS } from './constants.js';
+
+/** Build a ModeContext whose only meaningful member is `approval`. */
+function ctxWithApproval(
+  confirm: (req: ApprovalRequest) => Promise<ApprovalDecision>,
+): ModeContext {
+  return { approval: { name: 'fake', confirm } } as unknown as ModeContext;
+}
+
+const headlessCtx = {} as unknown as ModeContext;
+
+describe('runQueryApprovalGate', () => {
+  it('auto-approves headlessly when no resolver is present', async () => {
+    const res = await runQueryApprovalGate(headlessCtx, 'plan', 3, 0);
+    expect(res).toEqual({ outcome: { kind: 'approve' }, redraftCount: 0 });
+  });
+
+  it('approve maps to an approve outcome and preserves redraftCount', async () => {
+    const ctx = ctxWithApproval(async () => ({ optionId: 'approve' }));
+    const res = await runQueryApprovalGate(ctx, 'plan', 2, 1);
+    expect(res).toEqual({ outcome: { kind: 'approve' }, redraftCount: 1 });
+  });
+
+  it('cancel maps to a cancel outcome and preserves redraftCount', async () => {
+    const ctx = ctxWithApproval(async () => ({ optionId: 'cancel' }));
+    const res = await runQueryApprovalGate(ctx, 'plan', 2, 1);
+    expect(res).toEqual({ outcome: { kind: 'cancel' }, redraftCount: 1 });
+  });
+
+  it('redraft carries feedback text and increments the count', async () => {
+    const ctx = ctxWithApproval(async () => ({ optionId: 'redraft', text: 'narrow scope' }));
+    const res = await runQueryApprovalGate(ctx, 'plan', 2, 0);
+    expect(res).toEqual({
+      outcome: { kind: 'redraft', feedback: 'narrow scope' },
+      redraftCount: 1,
+    });
+  });
+
+  it('redraft with no text yields null feedback', async () => {
+    const ctx = ctxWithApproval(async () => ({ optionId: 'redraft' }));
+    const res = await runQueryApprovalGate(ctx, 'plan', 2, 0);
+    expect(res.outcome).toEqual({ kind: 'redraft', feedback: null });
+  });
+
+  it('the (MAX_REDRAFTS+1)th redraft trips the cap, not before', async () => {
+    const ctx = ctxWithApproval(async () => ({ optionId: 'redraft' }));
+    // The last allowed redraft: redraftCount goes from MAX_REDRAFTS-1 to MAX_REDRAFTS.
+    const allowed = await runQueryApprovalGate(ctx, 'plan', 1, MAX_REDRAFTS - 1);
+    expect(allowed.outcome.kind).toBe('redraft');
+    expect(allowed.redraftCount).toBe(MAX_REDRAFTS);
+    // One more pushes nextCount past the cap.
+    const capped = await runQueryApprovalGate(ctx, 'plan', 1, MAX_REDRAFTS);
+    expect(capped.outcome.kind).toBe('redraft-cap-exceeded');
+    expect(capped.redraftCount).toBe(MAX_REDRAFTS + 1);
+  });
+});
+
+describe('runSynthesisApprovalGate', () => {
+  it('auto-synthesizes headlessly when no resolver is present', async () => {
+    const res = await runSynthesisApprovalGate(headlessCtx, 'digest');
+    expect(res).toEqual({ kind: 'synthesize' });
+  });
+
+  it('synthesize option maps to synthesize', async () => {
+    const confirm = vi.fn(async () => ({ optionId: 'synthesize' }));
+    const res = await runSynthesisApprovalGate(ctxWithApproval(confirm), 'digest');
+    expect(res).toEqual({ kind: 'synthesize' });
+    expect(confirm).toHaveBeenCalledOnce();
+  });
+
+  it('cancel option maps to cancel', async () => {
+    const res = await runSynthesisApprovalGate(
+      ctxWithApproval(async () => ({ optionId: 'cancel' })),
+      'digest',
+    );
+    expect(res).toEqual({ kind: 'cancel' });
+  });
+});

package/src/approval.ts

@@ -0,0 +1,105 @@
+import type { ModeContext } from '@moxxy/sdk';
+
+import { MAX_REDRAFTS } from './constants.js';
+
+export type QueryGateOutcome =
+  | { kind: 'approve' }
+  | { kind: 'redraft'; feedback: string | null }
+  | { kind: 'cancel' }
+  | { kind: 'redraft-cap-exceeded' };
+
+/**
+ * Optional approval gate after the query plan is produced. Headless
+ * contexts (no resolver) auto-approve. Approve / redraft-with-feedback /
+ * cancel option ids, with bounded redraft retries.
+ */
+export async function runQueryApprovalGate(
+  ctx: ModeContext,
+  planText: string,
+  queryCount: number,
+  redraftCount: number,
+): Promise<{ outcome: QueryGateOutcome; redraftCount: number }> {
+  if (!ctx.approval) return { outcome: { kind: 'approve' }, redraftCount };
+
+  const decision = await ctx.approval.confirm({
+    title: 'Query plan ready — review before fan-out',
+    body: planText,
+    kind: 'deep-research.queries',
+    defaultOptionId: 'approve',
+    options: [
+      {
+        id: 'approve',
+        label: 'Approve and fan out',
+        hotkey: 'a',
+        description: `Spawn ${queryCount} parallel subagent${queryCount === 1 ? '' : 's'} to research these.`,
+      },
+      {
+        id: 'redraft',
+        label: 'Redraft with feedback',
+        hotkey: 'r',
+        requestsText: true,
+        textPrompt: 'What should change about the query plan?',
+        description: 'Send feedback to the planner and get a new query plan.',
+      },
+      {
+        id: 'cancel',
+        label: 'Cancel this turn',
+        hotkey: 'c',
+        danger: true,
+      },
+    ],
+  });
+
+  if (decision.optionId === 'cancel') return { outcome: { kind: 'cancel' }, redraftCount };
+  if (decision.optionId === 'redraft') {
+    const nextCount = redraftCount + 1;
+    if (nextCount > MAX_REDRAFTS) {
+      return { outcome: { kind: 'redraft-cap-exceeded' }, redraftCount: nextCount };
+    }
+    return {
+      outcome: { kind: 'redraft', feedback: decision.text ?? null },
+      redraftCount: nextCount,
+    };
+  }
+  return { outcome: { kind: 'approve' }, redraftCount };
+}
+
+export type SynthesisGateOutcome =
+  | { kind: 'synthesize' }
+  | { kind: 'cancel' };
+
+/**
+ * Approval gate shown after fan-out, before the synthesis turn. Body is
+ * a short digest of each subagent's result so the user can sanity-check
+ * coverage before paying for synthesis tokens.
+ */
+export async function runSynthesisApprovalGate(
+  ctx: ModeContext,
+  digest: string,
+): Promise<SynthesisGateOutcome> {
+  if (!ctx.approval) return { kind: 'synthesize' };
+
+  const decision = await ctx.approval.confirm({
+    title: 'Fan-out complete — synthesize the final writeup?',
+    body: digest,
+    kind: 'deep-research.synthesis',
+    defaultOptionId: 'synthesize',
+    options: [
+      {
+        id: 'synthesize',
+        label: 'Synthesize',
+        hotkey: 's',
+        description: 'Combine the findings into the final writeup.',
+      },
+      {
+        id: 'cancel',
+        label: 'Cancel this turn',
+        hotkey: 'c',
+        danger: true,
+      },
+    ],
+  });
+
+  if (decision.optionId === 'cancel') return { kind: 'cancel' };
+  return { kind: 'synthesize' };
+}

package/src/constants.ts

@@ -0,0 +1,153 @@
+import { asPluginId } from '@moxxy/sdk';
+
+export const RESEARCH_MODE_NAME = 'research';
+
+export const DEEP_RESEARCH_PLUGIN_ID = asPluginId('@moxxy/mode-deep-research');
+
+/**
+ * Asked once in the planning phase. The subagents fan out IN PARALLEL —
+ * which means a query can never depend on another query's output. If we
+ * let the planner emit "compare side A and side B" or "what are the
+ * disputed claims" as separate queries, the subagent running them has
+ * no idea what was actually gathered and either invents content or
+ * gives up (e.g. "I can't determine what 'the disputed claims' refers
+ * to from the prompt alone"). The synthesis phase already sees every
+ * subagent's findings end-to-end and is where comparison + contradiction
+ * analysis belongs — the planner's job is purely to spread the raw
+ * gathering work across independent angles.
+ */
+export const QUERY_PLAN_SYSTEM_PROMPT = `You are scoping a deep-research task. Produce 2-5 PARALLEL GATHERING queries — one per independent angle of raw evidence the synthesis phase will need.
+
+HARD RULES (the loop refuses plans that break these):
+- Each query MUST be independently answerable from web search + page reads ALONE — without seeing any other query's output. The subagents run in parallel and never see each other's findings.
+- DO NOT emit comparison, contradiction, "differences", "disputed claims", "which side is right", "balanced timeline", "verify side X's claims", or other queries that require knowing what OTHER queries returned. Those are the synthesis phase's job, not gathering.
+- DO NOT pad. If the user's question only needs 2 angles (e.g. "compare X side vs Y side"), emit exactly 2 queries — one per side. The synthesis turn does the comparison.
+- Each query should be concrete and scoped ("What did <party> say about <topic> in the last 30 days?"), not an open theme ("Background on X").
+- No two queries should be rephrasings of each other.
+
+Reply with EXACTLY this format and nothing else:
+
+QUERIES:
+1. <gathering query>
+2. <gathering query>
+...
+
+Stop after the last numbered line.`;
+
+/**
+ * System prompt for each fan-out subagent. They run in standard tool-use
+ * mode, but constrained (by allowedTools) to read-only web tools. The
+ * SOURCES: block is what the synthesis phase pulls citations from.
+ */
+export const SUBAGENT_SYSTEM_PROMPT = `You are a focused research subagent. You have ONE sub-question to answer. Use web_search and web_fetch (and Read for any local files referenced) to gather evidence, then produce a concise writeup.
+
+Stop tool-calling when you have enough material to answer. Reply with:
+
+FINDINGS:
+<2-4 short paragraphs answering the sub-question, citing sources inline like [1], [2] where claims come from a specific source>
+
+SOURCES:
+[1] <title> — <url>
+[2] <title> — <url>
+...
+
+Do NOT edit files. Do NOT run git. Stop after the last source line.`;
+
+/**
+ * Asked between fan-out rounds. Given the findings from the prior
+ * round(s), the model decides whether MORE parallel gathering is
+ * needed to fill specific gaps before synthesis — and if so, what.
+ * This is the "agentic" half of the loop that the user explicitly
+ * asked for: round-1 gathers Iran-side + USA-side, round-2 spawns
+ * follow-ups armed with both, instead of asking blind round-1
+ * subagents to compare things they can't see.
+ */
+export const FOLLOWUP_PLAN_SYSTEM_PROMPT = `You have the findings of the previous research round(s). Decide whether you need MORE parallel gathering to fill specific gaps the synthesis phase can't resolve on its own.
+
+You will receive:
+- The original user question.
+- Each prior subagent's question + FINDINGS + SOURCES block.
+
+Decision rules:
+- ONLY emit follow-ups when there is a CONCRETE gap that needs more raw evidence — a contradiction begging for a third source, a claim that needs primary-document verification, a missing data point that one round can't synthesize around.
+- The follow-up subagents WILL be given the prior findings as context in their prompt, so phrasing like "verify the casualty figure of X reported by Iranian state media against independent sources" is fine.
+- DO NOT emit follow-ups that just rephrase prior queries or chase tangents.
+- Each follow-up still runs in parallel with the others in this round, so follow-ups must be independent of EACH OTHER (just like round-1 queries).
+- If the prior findings are sufficient for a good synthesis, emit none and stop. The synthesis turn handles cross-cutting comparison without help.
+
+Reply with EXACTLY one of these formats and nothing else:
+
+FOLLOWUPS:
+1. <follow-up gathering query>
+2. <follow-up gathering query>
+...
+
+or
+
+FOLLOWUPS: (none)
+
+Stop after the last line.`;
+
+/**
+ * Synthesis turn: consume the per-subagent findings + sources and
+ * produce a single structured writeup with renumbered citations.
+ */
+export const SYNTHESIS_SYSTEM_PROMPT = `You are synthesizing a deep-research report from the findings of multiple subagents — possibly across multiple research rounds (an initial gathering round plus optional follow-up rounds that drilled into specific gaps the initial round surfaced).
+
+You will receive the original question, each subagent's question + round number + FINDINGS + SOURCES block. Produce the final writeup with these sections, in this order:
+
+## Executive summary
+<3-5 bullet points; the key takeaways.>
+
+## Key findings
+<numbered paragraphs covering each substantive finding, citing sources inline as [n] referring to the unified Sources list below. Call out contradictions explicitly. Mark gaps as "Not covered: …". When findings from a follow-up round resolve or amplify a contradiction the initial round surfaced, say so.>
+
+## Sources
+[1] <title> — <url>
+[2] <title> — <url>
+...
+(Renumber so the unified list is contiguous; each source appears once even if cited by multiple subagents.)
+
+## Open questions
+<bullets describing what remains unresolved, or "None — the gathered evidence is sufficient.">
+
+Be tight. Do not narrate your process.`;
+
+/** Refuse plans larger than this in the initial round — guards against runaway fan-out cost. */
+export const MAX_SUBAGENTS = 6;
+
+/** Maximum follow-up rounds after the initial gathering. */
+export const MAX_FOLLOWUP_ROUNDS = 2;
+
+/** Maximum follow-up queries per round. */
+export const MAX_FOLLOWUPS_PER_ROUND = 4;
+
+export const MAX_REDRAFTS = 3;
+
+export const SUBAGENT_MAX_ITERATIONS = 40;
+
+/**
+ * Per-finding character cap when a prior round's findings are embedded as
+ * context into EACH follow-up subagent's prompt. The same blob is duplicated
+ * across every sibling subagent and re-sent every round, so an uncapped
+ * multi-KB finding grows the embedded context multiplicatively. The full
+ * untruncated text is still used for the single synthesis turn.
+ */
+export const SUBAGENT_PRIOR_FINDING_MAX_CHARS = 1500;
+
+/**
+ * Tools each subagent is allowed to call. Constrained to read-only web +
+ * filesystem reads — no edits, no shell, no git, so a runaway subagent
+ * can't damage the working tree. WebSearch / WebFetch may be exposed
+ * under different names depending on plugin configuration; the registry
+ * silently ignores unknown names, so listing both common spellings is
+ * harmless.
+ */
+export const SUBAGENT_ALLOWED_TOOLS = [
+  'WebSearch',
+  'WebFetch',
+  'web_search',
+  'web_fetch',
+  'Read',
+  'read',
+] as const;

package/src/fanout-phase.ts

@@ -0,0 +1,177 @@
+import type { ModeContext, SubagentResult, SubagentSpec } from '@moxxy/sdk';
+
+import {
+  SUBAGENT_ALLOWED_TOOLS,
+  SUBAGENT_MAX_ITERATIONS,
+  SUBAGENT_PRIOR_FINDING_MAX_CHARS,
+  SUBAGENT_SYSTEM_PROMPT,
+} from './constants.js';
+
+export interface FanoutOutcome {
+  readonly results: ReadonlyArray<SubagentResult>;
+  readonly errored: ReadonlyArray<{ readonly index: number; readonly message: string }>;
+}
+
+/**
+ * Findings accumulated across rounds — each entry is one subagent's
+ * outcome plus the round it ran in. Synthesis and follow-up planning
+ * both work off this flat list.
+ */
+export interface RoundFinding {
+  readonly round: number;
+  readonly question: string;
+  readonly text: string;
+  readonly error?: string;
+}
+
+export function flattenOutcome(
+  round: number,
+  queries: ReadonlyArray<string>,
+  outcome: FanoutOutcome,
+): RoundFinding[] {
+  return queries.map((question, i) => {
+    const r = outcome.results[i];
+    const err = outcome.errored.find((e) => e.index === i);
+    return {
+      round,
+      question,
+      text: (r?.text ?? '').trim(),
+      ...(err ? { error: err.message } : {}),
+    };
+  });
+}
+
+/**
+ * Spawn one subagent per query in parallel, each constrained to web /
+ * read-only tools. When `priorFindings` is non-empty, the prior
+ * findings are embedded in each subagent's user prompt so follow-up
+ * agents see what earlier rounds already gathered (which is the whole
+ * point of multi-round research — round-2 follow-ups should not be
+ * blind to round-1's findings).
+ *
+ * Caller MUST have verified ctx.subagents is present.
+ */
+export async function runFanout(
+  ctx: ModeContext,
+  queries: ReadonlyArray<string>,
+  priorFindings: ReadonlyArray<RoundFinding> = [],
+): Promise<FanoutOutcome> {
+  if (!ctx.subagents) {
+    throw new Error('deep-research: runFanout called without ctx.subagents — caller bug');
+  }
+
+  const specs: SubagentSpec[] = queries.map((q, i) => ({
+    prompt: buildSubagentPrompt(q, priorFindings),
+    systemPrompt: SUBAGENT_SYSTEM_PROMPT,
+    mode: 'default',
+    maxIterations: SUBAGENT_MAX_ITERATIONS,
+    allowedTools: [...SUBAGENT_ALLOWED_TOOLS],
+    label: `subagent-${i + 1}`,
+  }));
+
+  let results: ReadonlyArray<SubagentResult>;
+  try {
+    results = await ctx.subagents.spawnAll(specs);
+  } catch (err) {
+    // spawnAll is Promise.all under the hood (run-child.ts) — a single child's
+    // setup work (strategy/model resolution, log appends, tool-registry build)
+    // throwing OUTSIDE its own try/catch rejects the whole batch. Treat that as
+    // every-subagent-errored rather than letting the rejection crash the entire
+    // research turn and discard all prior-round findings. flattenOutcome turns
+    // these into RoundFinding rows the loop carries into synthesis.
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      results: [],
+      errored: queries.map((_, index) => ({ index, message })),
+    };
+  }
+
+  const errored: Array<{ index: number; message: string }> = [];
+  results.forEach((r, i) => {
+    if (r.error) errored.push({ index: i, message: r.error.message });
+  });
+  return { results, errored };
+}
+
+function buildSubagentPrompt(
+  query: string,
+  priorFindings: ReadonlyArray<RoundFinding>,
+): string {
+  if (priorFindings.length === 0) return query;
+  const sections: string[] = [];
+  sections.push(
+    'Earlier research rounds gathered the following findings — use them as context for the focused question at the bottom, but you still need to do your own search to answer the focused question.',
+  );
+  sections.push('');
+  for (const f of priorFindings) {
+    sections.push(`### Round ${f.round}: ${f.question}`);
+    if (f.error) {
+      sections.push(`(errored: ${f.error})`);
+    } else {
+      // Cap each embedded finding: the SAME prior-findings blob is duplicated
+      // into every sibling subagent's prompt every round, so unbounded text
+      // grows multiplicatively and can blow the subagent's context window. The
+      // full untruncated text is preserved only for the single synthesis turn.
+      sections.push(capFindingText(f.text) || '(empty response)');
+    }
+    sections.push('');
+  }
+  sections.push('---');
+  sections.push('');
+  sections.push(`Your focused follow-up question:\n${query}`);
+  return sections.join('\n');
+}
+
+/** Bound a prior finding's text before it is embedded into a subagent prompt. */
+function capFindingText(text: string): string {
+  if (text.length <= SUBAGENT_PRIOR_FINDING_MAX_CHARS) return text;
+  return `${text.slice(0, SUBAGENT_PRIOR_FINDING_MAX_CHARS)}\n…[truncated]`;
+}
+
+/**
+ * Build a one-screen digest of subagent outcomes for the synthesis gate.
+ * Each entry shows the sub-question and a 200-char headline of the
+ * findings, plus a clear marker for any subagent that errored.
+ */
+export function buildFanoutDigest(findings: ReadonlyArray<RoundFinding>): string {
+  const total = findings.length;
+  const errored = findings.filter((f) => f.error).length;
+  const ok = total - errored;
+  const head = `${ok} of ${total} subagent${total === 1 ? '' : 's'} returned`;
+  const errStub = errored > 0 ? `, ${errored} errored` : '';
+
+  const blocks = findings.map((f, i) => {
+    if (f.error) {
+      return `${i + 1}. [round ${f.round}] ${f.question}\n   [errored: ${f.error}]`;
+    }
+    const headline = f.text.trim().slice(0, 200).replace(/\n+/g, ' ');
+    return `${i + 1}. [round ${f.round}] ${f.question}\n   ${headline || '(empty response)'}`;
+  });
+
+  return `${head}${errStub}.\n\n${blocks.join('\n\n')}`;
+}
+
+/**
+ * Build the synthesis turn's user message: weaves the original question
+ * back together with each subagent's writeup so the synthesizer has the
+ * raw material to cite and combine.
+ */
+export function buildSynthesisInput(
+  originalPrompt: string,
+  findings: ReadonlyArray<RoundFinding>,
+): string {
+  const parts: string[] = [];
+  parts.push(`Original question:\n${originalPrompt}`);
+  parts.push('');
+  parts.push('Sub-question findings:');
+  findings.forEach((f, i) => {
+    parts.push('');
+    parts.push(`### #${i + 1} (round ${f.round}): ${f.question}`);
+    if (f.error) {
+      parts.push(`(errored: ${f.error})`);
+    } else {
+      parts.push(f.text || '(empty response)');
+    }
+  });
+  return parts.join('\n');
+}