@demigodmode/pi-web-agent 0.2.2 → 0.4.0

package/README.md

@@ -6,12 +6,9 @@
 
 `@demigodmode/pi-web-agent` is a Pi package for web access.
 
-The whole point is keeping the boundaries straight:
+Most agent web tools blur search, fetch, browser rendering, and research into one vague thing. `pi-web-agent` exposes one public research tool, `web_explore`, and keeps search/fetch/headless work inside that bounded workflow.
 
-- `web_search` is for discovery
-- `web_fetch` is for plain HTTP reads
-- `web_fetch_headless` is the explicit browser path
-- `web_explore` is the bounded research path
+The point is keeping the model-facing boundary simple: ask `web_explore` to research a question, and it handles discovery, HTTP reads, targeted browser rendering, source ranking, and caveats internally.
 
 That sounds obvious, but a lot of agent tooling gets fuzzy right there. This package is meant to be stricter about what it actually did and more willing to say when a read was not good enough to trust.
 
@@ -45,6 +42,65 @@ Build the docs:
 npm run docs:build
 ```
 
+## Presentation modes
+
+`pi-web-agent` renders web tool output in one visible mode at a time:
+
+- `compact` — short summary, default everywhere
+- `preview` — slightly richer bounded view
+- `verbose` — fuller bounded view
+
+See the `v0.3.0` release notes for a before/after of the transcript cleanup:
+
+- https://github.com/demigodmode/pi-web-agent/releases/tag/v0.3.0
+
+## Settings
+
+Primary UI:
+
+```text
+/web-agent settings
+```
+
+Helper commands:
+
+```text
+/web-agent show
+/web-agent reset project
+/web-agent reset global
+/web-agent mode preview
+/web-agent mode web_explore verbose
+/web-agent mode web_explore inherit
+```
+
+Config files:
+
+```text
+Global:  ~/.pi/agent/extensions/pi-web-agent/config.json
+Project: .pi/extensions/pi-web-agent/config.json
+```
+
+Precedence:
+
+- built-in defaults
+- global config
+- project config
+
+Project config overrides global config.
+
+Example:
+
+```json
+{
+  "presentation": {
+    "defaultMode": "compact",
+    "tools": {
+      "web_explore": { "mode": "verbose" }
+    }
+  }
+}
+```
+
 ## Local development
 
 ```bash

package/dist/commands/web-agent-config.d.ts

@@ -0,0 +1,23 @@
+import { type ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { loadPresentationConfigLayers, type LoadedPresentationConfig } from '../presentation/config-store.js';
+import type { PresentationConfig, PresentationConfigOverride, PresentationScope } from '../presentation/types.js';
+type CommandDeps = {
+    load?: () => ReturnType<typeof loadPresentationConfigLayers>;
+    save?: (scope: PresentationScope, config: PresentationConfigOverride) => Promise<void>;
+    reset?: (scope: PresentationScope) => Promise<void>;
+};
+export type SettingsDraftState = {
+    scope: PresentationScope;
+    drafts: Record<PresentationScope, PresentationConfig>;
+    config: PresentationConfig;
+};
+export declare function getInheritedConfigForScope(loaded: Awaited<LoadedPresentationConfig>, scope: PresentationScope): PresentationConfig;
+export declare function getScopeDisplayConfig(loaded: Awaited<LoadedPresentationConfig>, scope: PresentationScope): PresentationConfig;
+export declare function createSettingsDraftState(loaded: Awaited<LoadedPresentationConfig>, initialScope: PresentationScope): SettingsDraftState;
+export declare function applySettingsValue(state: SettingsDraftState, id: string, newValue: string): SettingsDraftState;
+export declare function collapsePresentationConfigToOverride(config: PresentationConfig, inheritedConfig: PresentationConfig): PresentationConfigOverride;
+export declare function handleSettingsShortcut(data: string): {
+    action: 'cancel' | 'reset' | 'save';
+} | undefined;
+export declare function registerWebAgentConfigCommands(pi: ExtensionAPI, deps?: CommandDeps): void;
+export {};

package/dist/commands/web-agent-config.js

@@ -0,0 +1,249 @@
+import { getSettingsListTheme } from '@mariozechner/pi-coding-agent';
+import { Container, SettingsList, Text } from '@mariozechner/pi-tui';
+import { DEFAULT_PRESENTATION_CONFIG, mergePresentationConfigLayers, resolvePresentationMode } from '../presentation/config.js';
+import { loadPresentationConfigLayers, resetPresentationConfigScope, savePresentationConfigScope } from '../presentation/config-store.js';
+const PRESENTATION_TOOL_NAMES = ['web_explore'];
+function parseScopeToken(token) {
+    return token === 'global' || token === 'project' ? token : undefined;
+}
+function clonePresentationConfig(config) {
+    return {
+        defaultMode: config.defaultMode,
+        tools: { ...config.tools }
+    };
+}
+function formatConfigSummary(config) {
+    const lines = [`defaultMode: ${config.defaultMode}`];
+    for (const toolName of PRESENTATION_TOOL_NAMES) {
+        lines.push(`${toolName}: ${config.tools[toolName]?.mode ?? 'inherit'}`);
+    }
+    return lines.join('\n');
+}
+function buildSettingsItems(scope, config) {
+    return [
+        {
+            id: 'scope',
+            label: 'Write scope',
+            currentValue: scope,
+            values: ['project', 'global']
+        },
+        {
+            id: 'defaultMode',
+            label: 'Default mode',
+            currentValue: config.defaultMode,
+            values: ['compact', 'preview', 'verbose']
+        },
+        ...PRESENTATION_TOOL_NAMES.map((toolName) => ({
+            id: `tool:${toolName}`,
+            label: toolName,
+            currentValue: config.tools[toolName]?.mode ?? 'inherit',
+            values: ['inherit', 'compact', 'preview', 'verbose']
+        }))
+    ];
+}
+function isToolName(value) {
+    return PRESENTATION_TOOL_NAMES.includes(value);
+}
+function isModeOrInherit(value) {
+    return ['inherit', 'compact', 'preview', 'verbose'].includes(value);
+}
+export function getInheritedConfigForScope(loaded, scope) {
+    if (scope === 'global') {
+        return DEFAULT_PRESENTATION_CONFIG;
+    }
+    return mergePresentationConfigLayers(DEFAULT_PRESENTATION_CONFIG, loaded.global.rawConfig);
+}
+export function getScopeDisplayConfig(loaded, scope) {
+    if (scope === 'global') {
+        return mergePresentationConfigLayers(DEFAULT_PRESENTATION_CONFIG, loaded.global.rawConfig);
+    }
+    return mergePresentationConfigLayers(DEFAULT_PRESENTATION_CONFIG, loaded.global.rawConfig, loaded.project.rawConfig);
+}
+export function createSettingsDraftState(loaded, initialScope) {
+    const drafts = {
+        global: getScopeDisplayConfig(loaded, 'global'),
+        project: getScopeDisplayConfig(loaded, 'project')
+    };
+    return {
+        scope: initialScope,
+        drafts,
+        config: clonePresentationConfig(drafts[initialScope])
+    };
+}
+export function applySettingsValue(state, id, newValue) {
+    const nextDrafts = {
+        global: clonePresentationConfig(state.drafts.global),
+        project: clonePresentationConfig(state.drafts.project)
+    };
+    let nextScope = state.scope;
+    if (id === 'scope' && (newValue === 'project' || newValue === 'global')) {
+        nextScope = newValue;
+        return {
+            scope: nextScope,
+            drafts: nextDrafts,
+            config: clonePresentationConfig(nextDrafts[nextScope])
+        };
+    }
+    const currentDraft = clonePresentationConfig(nextDrafts[nextScope]);
+    if (id === 'defaultMode' && (newValue === 'compact' || newValue === 'preview' || newValue === 'verbose')) {
+        currentDraft.defaultMode = newValue;
+    }
+    if (id.startsWith('tool:')) {
+        const toolName = id.slice('tool:'.length);
+        const nextTools = { ...currentDraft.tools };
+        if (newValue === 'inherit') {
+            delete nextTools[toolName];
+        }
+        else if (newValue === 'compact' ||
+            newValue === 'preview' ||
+            newValue === 'verbose') {
+            nextTools[toolName] = { mode: newValue };
+        }
+        currentDraft.tools = nextTools;
+    }
+    nextDrafts[nextScope] = currentDraft;
+    return {
+        scope: nextScope,
+        drafts: nextDrafts,
+        config: clonePresentationConfig(nextDrafts[nextScope])
+    };
+}
+export function collapsePresentationConfigToOverride(config, inheritedConfig) {
+    const tools = Object.fromEntries(PRESENTATION_TOOL_NAMES.flatMap((toolName) => {
+        const configuredMode = config.tools[toolName]?.mode;
+        if (!configuredMode) {
+            return [];
+        }
+        const inheritedMode = resolvePresentationMode(toolName, inheritedConfig);
+        if (configuredMode === inheritedMode) {
+            return [];
+        }
+        return [[toolName, { mode: configuredMode }]];
+    }));
+    return {
+        defaultMode: config.defaultMode === inheritedConfig.defaultMode ? undefined : config.defaultMode,
+        tools
+    };
+}
+export function handleSettingsShortcut(data) {
+    if (data === '\u001b') {
+        return { action: 'cancel' };
+    }
+    if (data === '\u0012') {
+        return { action: 'reset' };
+    }
+    if (data === '\u0013') {
+        return { action: 'save' };
+    }
+    return undefined;
+}
+async function openSettingsUi(ctx, loaded, initialScope) {
+    return ctx.ui.custom((_tui, theme, _kb, done) => {
+        let state = createSettingsDraftState(loaded, initialScope);
+        let settingsList;
+        const container = new Container();
+        container.addChild(new Text(theme.fg('accent', theme.bold('pi-web-agent settings')), 1, 1));
+        container.addChild(new Text(theme.fg('muted', 'Ctrl+S save · Ctrl+R reset scope · Esc cancel'), 1, 2));
+        const rebuildSettingsList = () => {
+            if (settingsList) {
+                container.removeChild(settingsList);
+            }
+            settingsList = new SettingsList(buildSettingsItems(state.scope, state.config), Math.min(PRESENTATION_TOOL_NAMES.length + 8, 18), getSettingsListTheme(), (id, newValue) => {
+                state = applySettingsValue(state, id, newValue);
+                rebuildSettingsList();
+                container.invalidate();
+            }, () => done({ action: 'save', scope: state.scope, config: state.config }), { enableSearch: true });
+            container.addChild(settingsList);
+        };
+        rebuildSettingsList();
+        return {
+            render: (width) => container.render(width),
+            invalidate: () => container.invalidate(),
+            handleInput: (data) => {
+                const shortcut = handleSettingsShortcut(JSON.stringify(data).slice(1, -1));
+                if (shortcut?.action === 'cancel') {
+                    done({ action: 'cancel' });
+                    return;
+                }
+                if (shortcut?.action === 'reset') {
+                    done({ action: 'reset', scope: state.scope });
+                    return;
+                }
+                if (shortcut?.action === 'save') {
+                    done({ action: 'save', scope: state.scope, config: state.config });
+                    return;
+                }
+                settingsList.handleInput?.(data);
+            }
+        };
+    });
+}
+export function registerWebAgentConfigCommands(pi, deps = {}) {
+    const load = deps.load ?? (() => loadPresentationConfigLayers());
+    const save = deps.save ?? ((scope, config) => savePresentationConfigScope({}, scope, config));
+    const reset = deps.reset ?? ((scope) => resetPresentationConfigScope({}, scope));
+    pi.registerCommand('web-agent', {
+        description: 'Open settings or manage pi-web-agent presentation config',
+        handler: async (args, ctx) => {
+            const [action, maybeScope] = (args ?? '').trim().split(/\s+/).filter(Boolean);
+            if (action === 'show') {
+                const loaded = await load();
+                ctx.ui.notify([
+                    formatConfigSummary(loaded.effectiveConfig),
+                    `global: ${loaded.global.path}${loaded.global.exists ? '' : ' (missing)'}`,
+                    `project: ${loaded.project.path}${loaded.project.exists ? '' : ' (missing)'}`
+                ].join('\n'), 'info');
+                return;
+            }
+            if (action === 'reset') {
+                const scope = parseScopeToken(maybeScope) ?? 'project';
+                await reset(scope);
+                ctx.ui.notify(`Reset ${scope} config`, 'info');
+                return;
+            }
+            if (action === 'mode') {
+                const [, first, second] = (args ?? '').trim().split(/\s+/).filter(Boolean);
+                const loaded = await load();
+                const scope = 'project';
+                const baseConfig = getScopeDisplayConfig(loaded, scope);
+                const inheritedConfig = getInheritedConfigForScope(loaded, scope);
+                if (first && isModeOrInherit(first) && first !== 'inherit') {
+                    await save(scope, collapsePresentationConfigToOverride({ ...baseConfig, defaultMode: first }, inheritedConfig));
+                    ctx.ui.notify(`Saved project default mode = ${first}`, 'info');
+                    return;
+                }
+                if (first && second && isToolName(first) && isModeOrInherit(second)) {
+                    const nextTools = { ...baseConfig.tools };
+                    if (second === 'inherit') {
+                        delete nextTools[first];
+                    }
+                    else {
+                        nextTools[first] = { mode: second };
+                    }
+                    await save(scope, collapsePresentationConfigToOverride({ ...baseConfig, tools: nextTools }, inheritedConfig));
+                    ctx.ui.notify(`Saved project ${first} = ${second}`, 'info');
+                    return;
+                }
+                ctx.ui.notify('Usage: /web-agent mode <compact|preview|verbose> or /web-agent mode <tool> <inherit|compact|preview|verbose>', 'info');
+                return;
+            }
+            if (!action || action === 'settings') {
+                const loaded = await load();
+                const initialScope = 'project';
+                const result = await openSettingsUi(ctx, loaded, initialScope);
+                if (!result || result.action === 'cancel') {
+                    return;
+                }
+                if (result.action === 'reset') {
+                    await reset(result.scope);
+                    ctx.ui.notify(`Reset ${result.scope} config`, 'info');
+                    return;
+                }
+                await save(result.scope, collapsePresentationConfigToOverride(result.config, getInheritedConfigForScope(loaded, result.scope)));
+                ctx.ui.notify(`Saved ${result.scope} config`, 'info');
+                return;
+            }
+            ctx.ui.notify('Use /web-agent, /web-agent show, /web-agent reset project, or /web-agent settings', 'info');
+        }
+    });
+}

package/dist/extension.js

@@ -1,74 +1,38 @@
 import { Type } from '@sinclair/typebox';
+import { registerWebAgentConfigCommands } from './commands/web-agent-config.js';
+import { DEFAULT_PRESENTATION_CONFIG, resolvePresentationMode } from './presentation/config.js';
+import { loadPresentationConfigLayers } from './presentation/config-store.js';
+import { selectPresentationView } from './presentation/select-view.js';
 import { createWebExploreTool } from './tools/web-explore.js';
-import { createWebFetchTool } from './tools/web-fetch.js';
-import { createWebFetchHeadlessTool } from './tools/web-fetch-headless.js';
-import { createWebSearchTool } from './tools/web-search.js';
+async function getEffectivePresentationConfig(pi) {
+    const store = pi.__presentationConfigStore;
+    try {
+        const loaded = await (store?.load?.() ?? loadPresentationConfigLayers());
+        return loaded.effectiveConfig;
+    }
+    catch {
+        return DEFAULT_PRESENTATION_CONFIG;
+    }
+}
+async function renderToolText(pi, toolName, details) {
+    const config = await getEffectivePresentationConfig(pi);
+    const mode = resolvePresentationMode(toolName, config);
+    return selectPresentationView(details.presentation, mode) ?? JSON.stringify(details, null, 2);
+}
 export default function extension(pi) {
-    const webSearch = createWebSearchTool();
-    const webFetch = createWebFetchTool();
-    const webFetchHeadless = createWebFetchHeadlessTool();
-    const webExplore = createWebExploreTool();
-    pi.on('before_agent_start', async (event) => {
-        return {
-            systemPrompt: `${event.systemPrompt}\n\n` +
-                'For web research questions that require finding and comparing multiple sources, prefer web_explore. ' +
-                'Use web_search, web_fetch, and web_fetch_headless for direct/manual operations like explicit search calls, specific URL reads, or debugging. ' +
-                'After using web_explore, only call low-level web tools if there is a specific unresolved gap. ' +
-                'Do not keep searching or fetching just for extra confirmation.'
-        };
-    });
-    pi.registerTool({
-        name: 'web_search',
-        label: 'Web Search',
-        description: 'Direct search tool for manual discovery of links and snippets. Use for explicit search requests or when the user wants raw search results. Prefer web_explore for broader research questions.',
-        parameters: Type.Object({
-            query: Type.String({ description: 'Search query.' })
-        }),
-        async execute(_toolCallId, params) {
-            const result = await webSearch({ query: params.query });
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                details: result,
-                isError: result.status === 'error'
-            };
-        }
-    });
-    pi.registerTool({
-        name: 'web_fetch',
-        label: 'Web Fetch',
-        description: 'Direct HTTP page fetch for a specific URL. Use when the user wants one page read directly. Prefer web_explore for broader research across multiple sources.',
-        parameters: Type.Object({
-            url: Type.String({ description: 'HTTP or HTTPS URL to fetch.' })
-        }),
-        async execute(_toolCallId, params) {
-            const result = await webFetch({ url: params.url });
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                details: result,
-                isError: result.status === 'error'
-            };
-        }
-    });
-    pi.registerTool({
-        name: 'web_fetch_headless',
-        label: 'Web Fetch Headless',
-        description: 'Direct headless page fetch for a specific URL when browser rendering is explicitly needed. Prefer web_explore for research tasks; it decides headless escalation internally.',
-        parameters: Type.Object({
-            url: Type.String({ description: 'HTTP or HTTPS URL to fetch in headless mode.' })
-        }),
-        async execute(_toolCallId, params) {
-            const result = await webFetchHeadless({ url: params.url });
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                details: result,
-                isError: result.status === 'error'
-            };
-        }
-    });
+    registerWebAgentConfigCommands(pi);
+    const webExplore = pi.__webExploreTool ??
+        createWebExploreTool();
+    pi.on('before_agent_start', async (event) => ({
+        systemPrompt: `${event.systemPrompt}\n\n` +
+            'For web research questions that require finding and comparing sources, use web_explore. ' +
+            'web_explore handles search, fetch, source ranking, and headless escalation internally. ' +
+            'If more web evidence is needed after web_explore, call web_explore again with a narrower query; do not use shell/network commands such as curl, Invoke-WebRequest, npm view/search/pack, or direct HTTP URLs for web research.'
+    }));
     pi.registerTool({
         name: 'web_explore',
         label: 'Web Explore',
-        description: 'Research a web question using bounded search/fetch passes, source ranking, and targeted headless escalation. Prefer this for multi-source web research, current docs/discussion lookups, and recommendation summaries. Use this instead of chaining low-level web tools for the same research task.',
+        description: 'Research a web question using bounded search/fetch passes, source ranking, and targeted headless escalation. Use this for web research, current docs/discussion lookups, and recommendation summaries.',
         parameters: Type.Object({
             query: Type.String({ description: 'Web research question to explore.' })
         }),
@@ -78,7 +42,7 @@ export default function extension(pi) {
                 content: [
                     {
                         type: 'text',
-                        text: result.status === 'ok' ? result.text : JSON.stringify(result, null, 2)
+                        text: await renderToolText(pi, 'web_explore', result)
                     }
                 ],
                 details: result,

package/dist/orchestration/answer-synthesizer.d.ts

@@ -0,0 +1,8 @@
+import type { ResearchEvidence } from './research-types.js';
+export declare function synthesizeAnswer({ evidence, partial }: {
+    evidence: ResearchEvidence[];
+    partial: boolean;
+}): {
+    findings: string[];
+    caveat: string | undefined;
+};

package/dist/orchestration/answer-synthesizer.js

@@ -0,0 +1,17 @@
+function normalizeSummary(summary) {
+    return summary.replace(/\s+/g, ' ').trim();
+}
+export function synthesizeAnswer({ evidence, partial }) {
+    const findings = evidence.slice(0, 5).map((item) => {
+        const summary = normalizeSummary(item.summary);
+        return item.sourceKind === 'community' || item.sourceKind === 'issue-thread'
+            ? `Community/practical context: ${summary}`
+            : summary;
+    });
+    return {
+        findings,
+        caveat: partial
+            ? 'Evidence is partial, so this answer is based on the strongest source found within the bounded research budget.'
+            : undefined
+    };
+}

package/dist/orchestration/candidate-selector.d.ts

@@ -0,0 +1,6 @@
+import type { SearchResult } from '../types.js';
+export declare function selectCandidates({ results, seenUrls, maxCandidates }: {
+    results: SearchResult[];
+    seenUrls: Set<string>;
+    maxCandidates: number;
+}): SearchResult[];

package/dist/orchestration/candidate-selector.js

@@ -0,0 +1,24 @@
+function candidateScore(result) {
+    const url = result.url.toLowerCase();
+    if (url.includes('playwright.dev/docs') || url.includes('vitest.dev/guide') || url.includes('learn.microsoft.com'))
+        return 0;
+    if (url.includes('github.com/') && (url.includes('/issues/') || url.includes('/discussions/')))
+        return 1;
+    if (url.includes('github.com/'))
+        return 2;
+    if (url.includes('npmjs.com/package/'))
+        return 4;
+    return 3;
+}
+export function selectCandidates({ results, seenUrls, maxCandidates }) {
+    const deduped = new Map();
+    for (const result of results) {
+        if (seenUrls.has(result.url))
+            continue;
+        if (!deduped.has(result.url))
+            deduped.set(result.url, result);
+    }
+    return [...deduped.values()]
+        .sort((left, right) => candidateScore(left) - candidateScore(right))
+        .slice(0, maxCandidates);
+}

package/dist/orchestration/evidence-ranker.d.ts

@@ -0,0 +1,4 @@
+import type { ResearchEvidence } from './research-types.js';
+export declare function rankEvidence(evidence: ResearchEvidence[]): ResearchEvidence[];
+export declare function hasOfficialEvidence(evidence: ResearchEvidence[]): boolean;
+export declare function strongEvidenceCount(evidence: ResearchEvidence[]): number;

package/dist/orchestration/evidence-ranker.js

@@ -0,0 +1,36 @@
+function sourceRank(sourceKind) {
+    switch (sourceKind) {
+        case 'official-docs':
+            return 0;
+        case 'official-api':
+            return 1;
+        case 'official-discussion':
+            return 2;
+        case 'issue-thread':
+            return 3;
+        case 'community':
+            return 4;
+        case 'package-page':
+            return 5;
+        default:
+            return 6;
+    }
+}
+export function rankEvidence(evidence) {
+    const bestByUrl = new Map();
+    for (const item of evidence) {
+        const current = bestByUrl.get(item.url);
+        if (!current || sourceRank(item.sourceKind) < sourceRank(current.sourceKind)) {
+            bestByUrl.set(item.url, item);
+        }
+    }
+    return [...bestByUrl.values()].sort((left, right) => sourceRank(left.sourceKind) - sourceRank(right.sourceKind));
+}
+export function hasOfficialEvidence(evidence) {
+    return evidence.some((item) => item.sourceKind === 'official-docs' || item.sourceKind === 'official-api');
+}
+export function strongEvidenceCount(evidence) {
+    return evidence.filter((item) => item.sourceKind === 'official-docs' ||
+        item.sourceKind === 'official-api' ||
+        item.sourceKind === 'official-discussion').length;
+}

package/dist/orchestration/index.d.ts

@@ -13,29 +13,14 @@ export declare function createResearchWorkflow({ search, fetchPage, headlessFetc
     run({ query }: {
         query: string;
     }): Promise<{
-        decision: {
-            action: "answer";
-            rationale: string;
-            approvedEvidence: import("./research-types.js").ResearchEvidence[];
-        };
-        evidence: import("./research-types.js").ResearchEvidence[];
-        workerPass: import("./research-types.js").ResearchWorkerResult;
-    } | {
-        decision: {
-            action: "escalate-headless";
-            rationale: string;
-            url: string;
-            approvedEvidence: import("./research-types.js").ResearchEvidence[];
-        };
+        decision: import("./research-types.js").ResearchOrchestratorDecision;
         evidence: import("./research-types.js").ResearchEvidence[];
         workerPass: import("./research-types.js").ResearchWorkerResult;
-    } | {
-        decision: {
-            action: "research-again";
-            rationale: string;
-            followupQuery: string;
+        metadata: {
+            searchPasses: number;
+            fetchedPages: number;
+            headlessAttempts: number;
+            exhaustedBudget: boolean;
         };
-        evidence: import("./research-types.js").ResearchEvidence[];
-        workerPass: import("./research-types.js").ResearchWorkerResult;
     }>;
 };

package/dist/orchestration/query-planner.d.ts

@@ -0,0 +1,7 @@
+export type QueryPlanInput = {
+    originalQuery: string;
+    passIndex: number;
+    previousQueries: string[];
+    gaps: string[];
+};
+export declare function planSearchQueries(input: QueryPlanInput): string[];

package/dist/orchestration/query-planner.js

@@ -0,0 +1,37 @@
+function normalizeWhitespace(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function extractImportantWords(query) {
+    return normalizeWhitespace(query)
+        .replace(/\b(find|current|tell|me|how|to|the|and|with|for|in|a|an)\b/gi, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function officialSiteQuery(query) {
+    const lower = query.toLowerCase();
+    const terms = extractImportantWords(query);
+    if (lower.includes('vitest'))
+        return `site:vitest.dev ${terms}`;
+    if (lower.includes('playwright'))
+        return `site:playwright.dev ${terms}`;
+    if (lower.includes('microsoft edge') || lower.includes('edge'))
+        return `site:learn.microsoft.com ${terms}`;
+    return `${terms} official docs`;
+}
+function implementationQuery(query) {
+    return `site:github.com ${extractImportantWords(query)}`;
+}
+export function planSearchQueries(input) {
+    const planned = input.passIndex === 0
+        ? [input.originalQuery]
+        : [
+            officialSiteQuery(input.originalQuery),
+            implementationQuery(input.originalQuery),
+            `${extractImportantWords(input.originalQuery)} discussion`
+        ];
+    const previous = new Set(input.previousQueries.map(normalizeWhitespace));
+    return planned
+        .map(normalizeWhitespace)
+        .filter((query) => query && !previous.has(query))
+        .slice(0, 3);
+}