Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
import { logger } from '../utils/logger.js';
import { ResearchRun, type ResearchSnapshot } from './research-run.js';
export type ResearchModeState = 'off' | 'on';
/**
* Research is one run, not a sticky mode. "On" means the next message in the
* chat that asked (or any chat, when none was named) is researched; when that
* run ends — finished, cut short, stopped — research is off again, so the
* follow-up "thanks" isn't a 225-step research pass in every chat.
*/
export class ResearchMode {
private state: ResearchModeState = 'off';
private topic: string | null = null;
/** The chat it was switched on for; null = whichever message comes next. */
private armedFor: string | null = null;
private planFirst = false;
/**
* Runs going now, one per chat (ADR-037: chats run at once, so two can be
* researching together). Insertion order = start order.
*/
private runs = new Map<string, ResearchRun>();
/** The last run in each chat, for Continue / Retry and screens that open later. */
private lastRuns = new Map<string, ResearchRun>();
/** The chat the calling turn belongs to (set by the agent); null outside a turn. */
private scope: () => string | null = () => null;
/** Tell research which chat the calling code is working for (the agent's turn scope). */
setScope(resolver: () => string | null): void {
this.scope = resolver;
}
/**
* "The" run for the calling code: inside a turn, that chat's run (never
* another chat's); outside one (status screens), the newest run going.
*/
private get run(): ResearchRun | null {
const sessionId = this.scope();
if (sessionId !== null) return this.runs.get(sessionId) ?? null;
let newest: ResearchRun | null = null;
for (const r of this.runs.values()) newest = r;
return newest;
}
getState(): ResearchModeState {
return this.run ? 'on' : this.state;
}
isActive(): boolean {
return this.state === 'on' || this.run !== null;
}
setOn(topic?: string, opts: { sessionId?: string; planFirst?: boolean } = {}): void {
this.state = 'on';
this.topic = topic || null;
this.armedFor = opts.sessionId ?? null;
this.planFirst = !!opts.planFirst;
logger.info({ topic: this.topic, sessionId: this.armedFor, planFirst: this.planFirst }, 'Research mode: on');
}
/** Off for the next message; a run already going finishes (Stop ends it). */
setOff(): void {
this.state = 'off';
this.topic = null;
this.armedFor = null;
this.planFirst = false;
logger.info('Research mode: off');
}
toggle(): ResearchModeState {
if (this.state === 'off') this.setOn();
else this.setOff();
logger.info({ state: this.state }, 'Research mode toggled');
return this.state;
}
/** Is research switched on for this chat's next message? */
armedForSession(sessionId: string): boolean {
return this.state === 'on' && (this.armedFor === null || this.armedFor === sessionId);
}
isPlanFirst(): boolean {
return this.planFirst;
}
/** The message that starts the run arrived: research it. */
beginRun(sessionId: string, content: string, maxSteps: number): ResearchRun {
const run = new ResearchRun(this.topic || content.trim().slice(0, 160), sessionId, maxSteps, this.planFirst);
this.state = 'off';
this.armedFor = null;
this.planFirst = false;
this.runs.delete(sessionId);
this.runs.set(sessionId, run);
this.lastRuns.set(sessionId, run);
if (this.lastRuns.size > 50) this.lastRuns.delete(this.lastRuns.keys().next().value as string);
logger.info({ runId: run.id, sessionId, topic: run.topic }, 'Research run started');
return run;
}
currentRun(): ResearchRun | null {
return this.run;
}
/** The run for this chat: the one going, else its last one. */
runFor(sessionId: string): ResearchRun | null {
return this.runs.get(sessionId) ?? this.lastRuns.get(sessionId) ?? null;
}
/** The run going in this chat right now, if any. */
activeRunFor(sessionId: string): ResearchRun | null {
return this.runs.get(sessionId) ?? null;
}
/** What a screen opening this chat should show. */
stateFor(sessionId: string): { armed: boolean; planFirst: boolean; topic: string | null; run: ResearchSnapshot | null } {
const run = this.runFor(sessionId);
return { armed: this.armedForSession(sessionId), planFirst: this.planFirst, topic: this.topic, run: run ? run.snapshot() : null };
}
/** The run's turn is over (however it ended). Research is off again for that chat. */
endRun(sessionId?: string): void {
const run = sessionId !== undefined ? this.runs.get(sessionId) ?? null : this.run;
if (!run) return;
if (run.outcome === 'running') run.end('done');
logger.info({ runId: run.id, outcome: run.outcome }, 'Research run ended');
this.runs.delete(run.sessionId);
this.topic = null;
}
setTopic(topic: string): void {
this.topic = topic;
}
getTopic(): string | null {
return this.run?.topic ?? this.topic;
}
getStatusText(): string {
if (this.run) return `Research: running | Topic: ${this.run.topic}`;
if (this.state === 'off') return 'Research mode: Off';
let text = 'Research mode: On (for your next message)';
if (this.topic) text += ` | Topic: ${this.topic}`;
return text;
}
/**
* Multiplier applied to the per-task tool-call cap while a research run is going.
* Research requires many fetch/search iterations; keep the hard cap but raise it.
*/
getMaxStepsMultiplier(): number {
return this.run ? 3 : 1;
}
/**
* Multiplier applied to the foreground stall timeout while a research run is going.
* Research tasks run long by design; do not abort them as stalled.
*/
getStallMsMultiplier(): number {
return this.run ? 4 : 1;
}
getSystemPromptSuffix(): string {
if (!this.run) return '';
let suffix = '\n\n**RESEARCH MODE IS ACTIVE**';
suffix += '\nMode: RESEARCH';
suffix += '\nYou are performing deep research for the user. Your job is to produce a thorough, well-structured research article, not a quick chat answer.';
suffix += '\n\nResearch workflow:';
suffix += this.run.questions.length
? `\n1. The owner approved this plan. Call update_plan once with exactly these steps, then mark each one active and done as you cover it:\n${this.run.questions.map((q, i) => ` ${i + 1}. ${q}`).join('\n')}`
: '\n1. Break the question into 3-6 sub-questions. Call update_plan with them as steps, and mark each one active and done as you cover it — the owner watches that list.';
suffix += '\n2. ALWAYS use web_search and fetch_url to gather real, current information from the web. Do not rely on memory or prior knowledge for facts, dates, or news — verify everything live.';
suffix += '\n3. Build a visual plan while researching. Actively inspect source pages for relevant photos, diagrams, charts, maps, or infographics and preserve their original direct image URLs.';
suffix += '\n4. Cross-check claims across multiple sources. Prefer primary sources, official statements, and reputable outlets.';
suffix += '\n5. Take as many tool steps as the research genuinely requires — do not stop early. Long-running research is expected and will not be killed.';
suffix += '\n6. After gathering sources, synthesize a single comprehensive research article in rich markdown.';
suffix += '\n\nOutput format — produce ONE research article as rich markdown:';
suffix += '\n- Start with a `# Title` reflecting the research question.';
suffix += '\n- Include a short TL;DR summary near the top.';
suffix += '\n- Use `##` section headings for sub-topics.';
suffix += '\n- Cite sources inline as markdown links, e.g. "[according to NOAA](https://...)".';
suffix += '\n- Include 2-4 editorially relevant images when credible sources provide them: one strong lead image near the top and additional visuals beside the sections they support.';
suffix += '\n- Embed images as `` using the original public image URL, not a webpage URL, search-result thumbnail, local file, or invented URL.';
suffix += '\n- Prefer informative visuals over decoration. Do not repeat an image, and omit only when diligent source review finds no safe, relevant public image.';
suffix += '\n- Include a `## Sources` section at the end listing all URLs consulted.';
suffix += '\n- Write the whole article in your final reply, not in a file: Mercury saves your reply as the report file itself. Do not create or write a file for it, and do not reply with only a summary.';
suffix += '\n- Between tool calls, say nothing (no "Let me search…"); the owner sees each step live.';
suffix += '\n- When a source fails (blocked, timed out, not found), try another source for the same point; do not retry the same URL more than once. Mercury lists failed sources for the owner itself, so do not add your own list of them.';
suffix += '\n\nIf the conversation already holds an earlier report on this topic, build on it: keep what it established and extend or correct it.';
suffix += `\n\nResearch topic: ${this.run.topic}`;
return suffix;
}
}