@moxxy/mode-deep-research 0.26.0

package/src/query-phase.ts

@@ -0,0 +1,123 @@
+import {
+  buildSystemPromptWithSkills,
+  runSingleShotTurn,
+  type ModeContext,
+  type ProviderMessage,
+} from '@moxxy/sdk';
+
+import {
+  FOLLOWUP_PLAN_SYSTEM_PROMPT,
+  QUERY_PLAN_SYSTEM_PROMPT,
+} from './constants.js';
+import type { RoundFinding } from './fanout-phase.js';
+
+/**
+ * Drive the initial query-planning turn. Single-shot stream — the
+ * planner shouldn't be web-searching, that's the subagents' job.
+ * Returns the raw text, or null on provider error (already emitted).
+ */
+export async function collectQueryPlan(
+  ctx: ModeContext,
+  redraftFeedback: string | null,
+): Promise<string | null> {
+  const messages = buildPlannerMessages(
+    ctx,
+    QUERY_PLAN_SYSTEM_PROMPT,
+    buildInitialUserMessages(ctx, redraftFeedback),
+  );
+  return runSingleShotTurn(ctx, messages, { maxTokens: 800 });
+}
+
+/**
+ * Drive the follow-up planning turn between gather rounds. The model
+ * sees the prior round(s)' findings as context and decides whether to
+ * spawn more parallel research or move to synthesis.
+ */
+export async function collectFollowupPlan(
+  ctx: ModeContext,
+  originalPrompt: string,
+  priorFindings: ReadonlyArray<RoundFinding>,
+): Promise<string | null> {
+  const messages = buildPlannerMessages(
+    ctx,
+    FOLLOWUP_PLAN_SYSTEM_PROMPT,
+    buildFollowupUserMessages(originalPrompt, priorFindings),
+  );
+  return runSingleShotTurn(ctx, messages, { maxTokens: 800 });
+}
+
+function buildPlannerMessages(
+  ctx: ModeContext,
+  systemPrompt: string,
+  userMessages: ProviderMessage[],
+): ProviderMessage[] {
+  const systemWithSkills =
+    buildSystemPromptWithSkills(ctx.systemPrompt, ctx.skills.list()) ?? '';
+  return [
+    {
+      role: 'system',
+      content: [
+        {
+          type: 'text',
+          text: systemPrompt + (systemWithSkills ? `\n\n${systemWithSkills}` : ''),
+        },
+      ],
+    },
+    ...userMessages,
+  ];
+}
+
+function buildInitialUserMessages(
+  ctx: ModeContext,
+  redraftFeedback: string | null,
+): ProviderMessage[] {
+  const out: ProviderMessage[] = [];
+  for (const e of ctx.log.slice()) {
+    if (e.type === 'user_prompt') {
+      out.push({ role: 'user', content: [{ type: 'text', text: e.text }] });
+    }
+  }
+  if (redraftFeedback) {
+    out.push({
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text:
+            `The previous query plan needs to be redrafted. Feedback from the user: ${redraftFeedback}\n\n` +
+            `Produce a new QUERIES block addressing this feedback.`,
+        },
+      ],
+    });
+  }
+  return out;
+}
+
+function buildFollowupUserMessages(
+  originalPrompt: string,
+  priorFindings: ReadonlyArray<RoundFinding>,
+): ProviderMessage[] {
+  const sections: string[] = [];
+  sections.push(`Original question:\n${originalPrompt}`);
+  sections.push('');
+  sections.push('Prior research findings:');
+  for (const f of priorFindings) {
+    sections.push('');
+    sections.push(`### Round ${f.round}, sub-question: ${f.question}`);
+    if (f.error) {
+      sections.push(`(errored: ${f.error})`);
+    } else {
+      sections.push(f.text.trim() || '(empty response)');
+    }
+  }
+  sections.push('');
+  sections.push(
+    'Decide whether more parallel research is needed. Reply with a FOLLOWUPS: block as instructed.',
+  );
+  return [
+    {
+      role: 'user',
+      content: [{ type: 'text', text: sections.join('\n') }],
+    },
+  ];
+}

package/src/research-loop.ts

@@ -0,0 +1,414 @@
+import type { ModeContext, MoxxyEvent } from '@moxxy/sdk';
+
+import {
+  runQueryApprovalGate,
+  runSynthesisApprovalGate,
+} from './approval.js';
+import {
+  RESEARCH_MODE_NAME,
+  DEEP_RESEARCH_PLUGIN_ID,
+  MAX_FOLLOWUPS_PER_ROUND,
+  MAX_FOLLOWUP_ROUNDS,
+  MAX_REDRAFTS,
+  MAX_SUBAGENTS,
+} from './constants.js';
+import {
+  buildFanoutDigest,
+  buildSynthesisInput,
+  flattenOutcome,
+  runFanout,
+  type RoundFinding,
+} from './fanout-phase.js';
+import { parseFollowups, parseQueries } from './parse-queries.js';
+import { collectFollowupPlan, collectQueryPlan } from './query-phase.js';
+import { collectSynthesis } from './synthesis-phase.js';
+
+/**
+ * Deep-research loop:
+ *   1. Plan QUERIES: block (with redraft-able approval gate)
+ *   2. Fan out (round 1) — one subagent per gathering query, in parallel
+ *   3. Up to MAX_FOLLOWUP_ROUNDS of:
+ *        a. Ask model "given findings so far, do you need follow-ups?"
+ *        b. If yes, fan out follow-ups with the prior findings as
+ *           context in each subagent's prompt.
+ *        c. If no, break out.
+ *   4. Synthesis approval gate (digest of all rounds)
+ *   5. Synthesize the final cited writeup.
+ *
+ * Headless contexts auto-approve both gates. Missing ctx.subagents is
+ * fatal — fan-out is the whole point of this mode.
+ */
+export async function* runDeepResearchMode(ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+  if (ctx.signal.aborted) {
+    yield await ctx.emit({
+      type: 'abort',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      reason: 'aborted before deep-research start',
+    });
+    return;
+  }
+
+  if (!ctx.subagents) {
+    yield await ctx.emit({
+      type: 'error',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      kind: 'fatal',
+      message:
+        'research: ctx.subagents is unavailable (the @moxxy/plugin-subagents plugin appears disabled). ' +
+        'Re-enable it, or switch to the default mode for a serial alternative.',
+    });
+    return;
+  }
+
+  yield await ctx.emit({
+    type: 'mode_iteration',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    strategy: RESEARCH_MODE_NAME,
+    iteration: 0,
+    routing: 'unresolved',
+  });
+
+  // Phase 1: query plan (with redraftable gate).
+  const planning = yield* runPlanningPhase(ctx);
+  if (planning === null) return;
+  const { queries, originalPrompt } = planning;
+
+  // Phase 2: round-1 fan out.
+  const allFindings: RoundFinding[] = [];
+  const round1 = yield* runRound(ctx, 1, queries, []);
+  if (round1 === null) return;
+  allFindings.push(...round1);
+
+  // Phase 3: follow-up rounds, capped to MAX_FOLLOWUP_ROUNDS.
+  for (let round = 2; round <= MAX_FOLLOWUP_ROUNDS + 1; round += 1) {
+    if (ctx.signal.aborted) return;
+    const followups = yield* runFollowupPlan(ctx, originalPrompt, allFindings, round);
+    if (followups === null) return;
+    if (followups.length === 0) {
+      yield await ctx.emit({
+        type: 'plugin_event',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'plugin',
+        pluginId: DEEP_RESEARCH_PLUGIN_ID,
+        subtype: 'deep_research_followups_none',
+        payload: { round },
+      });
+      break;
+    }
+    const nextRound = yield* runRound(ctx, round, followups, allFindings);
+    if (nextRound === null) return;
+    allFindings.push(...nextRound);
+  }
+
+  if (ctx.signal.aborted) return;
+
+  // Phase 4: synthesis approval gate.
+  const digest = buildFanoutDigest(allFindings);
+  const gate = await runSynthesisApprovalGate(ctx, digest);
+  if (gate.kind === 'cancel') {
+    yield await ctx.emit({
+      type: 'abort',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'user',
+      reason: 'synthesis cancelled by user',
+    });
+    return;
+  }
+
+  // Phase 5: synthesize.
+  const synthesisInput = buildSynthesisInput(originalPrompt, allFindings);
+  const synthesisText = await collectSynthesis(ctx, synthesisInput);
+  if (synthesisText === null) return;
+
+  // Synthesis is a multi-second provider call; if the user aborted while it ran,
+  // emit an abort rather than the finished report — matching the abort discipline
+  // every other phase in this loop follows (see the ctx.signal.aborted guards above).
+  if (ctx.signal.aborted) {
+    yield await ctx.emit({
+      type: 'abort',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      reason: 'aborted during synthesis',
+    });
+    return;
+  }
+
+  yield await ctx.emit({
+    type: 'assistant_message',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'model',
+    content: synthesisText,
+    stopReason: 'end_turn',
+  });
+
+  yield await ctx.emit({
+    type: 'plugin_event',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'plugin',
+    pluginId: DEEP_RESEARCH_PLUGIN_ID,
+    subtype: 'deep_research_synthesis_completed',
+    payload: {
+      totalFindings: allFindings.length,
+      rounds: Math.max(...allFindings.map((f) => f.round), 1),
+      errored: allFindings.filter((f) => f.error).length,
+    },
+  });
+}
+
+/**
+ * One round of parallel fan-out — emits start/complete events around
+ * runFanout. Returns the per-round findings, or null on abort.
+ */
+async function* runRound(
+  ctx: ModeContext,
+  round: number,
+  queries: ReadonlyArray<string>,
+  priorFindings: ReadonlyArray<RoundFinding>,
+): AsyncGenerator<MoxxyEvent, RoundFinding[] | null, unknown> {
+  yield await ctx.emit({
+    type: 'plugin_event',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'plugin',
+    pluginId: DEEP_RESEARCH_PLUGIN_ID,
+    subtype: 'deep_research_fanout_started',
+    payload: { round, queries: queries.length },
+  });
+
+  const outcome = await runFanout(ctx, queries, priorFindings);
+
+  yield await ctx.emit({
+    type: 'plugin_event',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'plugin',
+    pluginId: DEEP_RESEARCH_PLUGIN_ID,
+    subtype: 'deep_research_fanout_completed',
+    payload: {
+      round,
+      total: queries.length,
+      errored: outcome.errored.length,
+    },
+  });
+
+  if (ctx.signal.aborted) return null;
+  return flattenOutcome(round, queries, outcome);
+}
+
+/**
+ * Ask the model whether to fan out more queries, given everything
+ * gathered so far. Returns the parsed follow-up queries (may be empty)
+ * or null on a fatal error.
+ */
+async function* runFollowupPlan(
+  ctx: ModeContext,
+  originalPrompt: string,
+  priorFindings: ReadonlyArray<RoundFinding>,
+  round: number,
+): AsyncGenerator<MoxxyEvent, string[] | null, unknown> {
+  yield await ctx.emit({
+    type: 'plugin_event',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'plugin',
+    pluginId: DEEP_RESEARCH_PLUGIN_ID,
+    subtype: 'deep_research_followups_planning',
+    payload: { round, basedOn: priorFindings.length },
+  });
+
+  const text = await collectFollowupPlan(ctx, originalPrompt, priorFindings);
+  if (text === null) return null;
+  const followups = parseFollowups(text);
+
+  // Apply cap and surface the trim as an event — but only when there's
+  // something to draft. The empty case is signalled by the caller via
+  // `deep_research_followups_none`; emitting a "drafted with kept=0"
+  // event here would be a duplicate "nothing to do" signal.
+  const trimmed = followups.slice(0, MAX_FOLLOWUPS_PER_ROUND);
+  if (trimmed.length === 0) return [];
+
+  yield await ctx.emit({
+    type: 'plugin_event',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'plugin',
+    pluginId: DEEP_RESEARCH_PLUGIN_ID,
+    subtype: 'deep_research_followups_drafted',
+    payload: {
+      round,
+      proposed: followups.length,
+      kept: trimmed.length,
+      queries: trimmed,
+    },
+  });
+
+  // Materialize the follow-up plan as an assistant_message so the user
+  // sees the queries that are about to run, even without an approval
+  // gate. (We deliberately skip a per-round approval gate to keep the
+  // user-facing checkpoints lightweight — the synthesis gate at the
+  // end is the final go/no-go.)
+  yield await ctx.emit({
+    type: 'assistant_message',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'model',
+    content:
+      `Follow-up round ${round} — spawning ${trimmed.length} more subagent${trimmed.length === 1 ? '' : 's'}:\n` +
+      trimmed.map((q, i) => `${i + 1}. ${q}`).join('\n'),
+    stopReason: 'end_turn',
+  });
+
+  return trimmed;
+}
+
+async function* runPlanningPhase(
+  ctx: ModeContext,
+): AsyncGenerator<
+  MoxxyEvent,
+  { queries: string[]; originalPrompt: string } | null,
+  unknown
+> {
+  // Capture the original prompt from the log so we can re-include it in
+  // synthesis context. Use the LAST user_prompt — the one that triggered this
+  // turn — to stay consistent with how the runner scopes a turn (a multi-turn
+  // session's earlier prompts would otherwise anchor synthesis on a stale
+  // question). null = no user prompt at all (empty log).
+  const originalPrompt = (() => {
+    const events = ctx.log.slice();
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      const e = events[i]!;
+      if (e.type === 'user_prompt') return e.text;
+    }
+    return null;
+  })();
+
+  if (originalPrompt === null) {
+    yield await ctx.emit({
+      type: 'error',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      kind: 'fatal',
+      message:
+        'deep-research: no user prompt found in the session log — nothing to research.',
+    });
+    return null;
+  }
+
+  let redraftFeedback: string | null = null;
+  let redraftCount = 0;
+
+  while (true) {
+    if (ctx.signal.aborted) {
+      yield await ctx.emit({
+        type: 'abort',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'system',
+        reason: 'aborted during planning',
+      });
+      return null;
+    }
+
+    const planText = await collectQueryPlan(ctx, redraftFeedback);
+    if (planText === null) return null;
+    const queries = parseQueries(planText);
+
+    yield await ctx.emit({
+      type: 'plugin_event',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'plugin',
+      pluginId: DEEP_RESEARCH_PLUGIN_ID,
+      subtype: 'deep_research_queries_drafted',
+      payload: { text: planText, queries, redraft: redraftCount },
+    });
+
+    if (queries.length === 0) {
+      yield await ctx.emit({
+        type: 'assistant_message',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'model',
+        content: planText,
+        stopReason: 'end_turn',
+      });
+      return null;
+    }
+
+    if (queries.length > MAX_SUBAGENTS) {
+      // Over-production is a normal, recoverable failure mode ("be exhaustive"
+      // prompts trip it easily). When an interactive resolver is present and we
+      // still have redraft budget, auto-redraft asking the planner to narrow,
+      // rather than killing the whole turn. Headless (no approval) or once the
+      // redraft cap is exhausted, fall through to the fatal abort.
+      const nextCount = redraftCount + 1;
+      if (ctx.approval && nextCount <= MAX_REDRAFTS) {
+        redraftCount = nextCount;
+        redraftFeedback =
+          `You produced ${queries.length} queries; the cap is ${MAX_SUBAGENTS}. ` +
+          `Return at most ${MAX_SUBAGENTS} parallel gathering queries.`;
+        continue;
+      }
+      yield await ctx.emit({
+        type: 'error',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'system',
+        kind: 'fatal',
+        message: `deep-research: refusing a ${queries.length}-query plan (cap is ${MAX_SUBAGENTS}). Narrow scope or rephrase.`,
+      });
+      return null;
+    }
+
+    const gate = await runQueryApprovalGate(ctx, planText, queries.length, redraftCount);
+    redraftCount = gate.redraftCount;
+
+    if (gate.outcome.kind === 'cancel') {
+      yield await ctx.emit({
+        type: 'abort',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'user',
+        reason: 'query plan rejected by user',
+      });
+      return null;
+    }
+    if (gate.outcome.kind === 'redraft-cap-exceeded') {
+      yield await ctx.emit({
+        type: 'error',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'system',
+        kind: 'fatal',
+        message: `deep-research: redrafted ${MAX_REDRAFTS}× without approval; aborting.`,
+      });
+      return null;
+    }
+    if (gate.outcome.kind === 'redraft') {
+      redraftFeedback = gate.outcome.feedback;
+      continue;
+    }
+
+    yield await ctx.emit({
+      type: 'assistant_message',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'model',
+      content: planText,
+      stopReason: 'end_turn',
+    });
+    return { queries, originalPrompt };
+  }
+}

package/src/synthesis-phase.ts

@@ -0,0 +1,25 @@
+import { runSingleShotTurn, type ModeContext, type ProviderMessage } from '@moxxy/sdk';
+
+import { SYNTHESIS_SYSTEM_PROMPT } from './constants.js';
+
+/**
+ * Run the synthesis turn: single-shot stream that consumes the
+ * per-subagent findings and produces the final structured writeup.
+ * Returns the assembled text or null on error.
+ */
+export async function collectSynthesis(
+  ctx: ModeContext,
+  inputBody: string,
+): Promise<string | null> {
+  const messages: ProviderMessage[] = [
+    {
+      role: 'system',
+      content: [{ type: 'text', text: SYNTHESIS_SYSTEM_PROMPT }],
+    },
+    {
+      role: 'user',
+      content: [{ type: 'text', text: inputBody }],
+    },
+  ];
+  return runSingleShotTurn(ctx, messages, { maxTokens: 4096 });
+}