@demigodmode/pi-web-agent 0.2.2 → 0.3.1

package/README.md

@@ -1,63 +1,119 @@
-# pi-web-agent
-
-[![CI](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@demigodmode/pi-web-agent)](https://www.npmjs.com/package/@demigodmode/pi-web-agent)
-[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://demigodmode.github.io/pi-web-agent/)
-
-`@demigodmode/pi-web-agent` is a Pi package for web access.
-
-The whole point is keeping the boundaries straight:
-
-- `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
-
-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.
-
-## Install
-
-```bash
-pi install npm:@demigodmode/pi-web-agent
-```
-
-Later on, update installed packages with:
-
-```bash
-pi update
-```
-
-## Docs
-
-Docs site:
-
-- https://demigodmode.github.io/pi-web-agent/
-
-Work on the docs locally:
-
-```bash
-npm run docs:dev
-```
-
-Build the docs:
-
-```bash
-npm run docs:build
-```
-
-## Local development
-
-```bash
-npm install
-npm test
-npm run lint
-npm run build
-```
-
-For local Pi work, this repo includes `.pi/extensions/pi-web-agent.ts`.
-
-If Pi is already running, use `/reload` after changes.
-
-## License
-
-AGPL-3.0-only. See `LICENSE`.
+# pi-web-agent
+
+[![CI](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@demigodmode/pi-web-agent)](https://www.npmjs.com/package/@demigodmode/pi-web-agent)
+[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://demigodmode.github.io/pi-web-agent/)
+
+`@demigodmode/pi-web-agent` is a Pi package for web access.
+
+The whole point is keeping the boundaries straight:
+
+- `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
+
+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.
+
+## Install
+
+```bash
+pi install npm:@demigodmode/pi-web-agent
+```
+
+Later on, update installed packages with:
+
+```bash
+pi update
+```
+
+## Docs
+
+Docs site:
+
+- https://demigodmode.github.io/pi-web-agent/
+
+Work on the docs locally:
+
+```bash
+npm run docs:dev
+```
+
+Build the docs:
+
+```bash
+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
+
+## 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_search verbose
+/web-agent mode web_search 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_search": { "mode": "preview" },
+      "web_explore": { "mode": "verbose" }
+    }
+  }
+}
+```
+
+## Local development
+
+```bash
+npm install
+npm test
+npm run lint
+npm run build
+```
+
+For local Pi work, this repo includes `.pi/extensions/pi-web-agent.ts`.
+
+If Pi is already running, use `/reload` after changes.
+
+## License
+
+AGPL-3.0-only. See `LICENSE`.

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,254 @@
+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_search',
+    'web_fetch',
+    'web_fetch_headless',
+    '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,14 +1,111 @@
 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) {
+    registerWebAgentConfigCommands(pi);
     const webSearch = createWebSearchTool();
     const webFetch = createWebFetchTool();
     const webFetchHeadless = createWebFetchHeadlessTool();
     const webExplore = createWebExploreTool();
+    let webExploreUsedInCurrentFlow = false;
+    const postWebExploreGuardError = {
+        code: 'POST_WEB_EXPLORE_GUARD',
+        message: 'web_explore already ran for this research task. Only use low-level web tools if there is a specific unresolved gap.'
+    };
+    async function guardSearchResponse() {
+        const result = {
+            status: 'error',
+            results: [],
+            metadata: {
+                backend: 'duckduckgo',
+                cacheHit: false
+            },
+            error: postWebExploreGuardError,
+            presentation: {
+                mode: 'compact',
+                views: {
+                    compact: `Search failed: ${postWebExploreGuardError.message}`
+                }
+            }
+        };
+        return {
+            content: [{ type: 'text', text: await renderToolText(pi, 'web_search', result) }],
+            details: result,
+            isError: true
+        };
+    }
+    async function guardFetchResponse(url) {
+        const result = {
+            status: 'error',
+            url,
+            metadata: {
+                method: 'http',
+                cacheHit: false
+            },
+            error: postWebExploreGuardError,
+            presentation: {
+                mode: 'compact',
+                views: {
+                    compact: `Fetch failed: ${postWebExploreGuardError.message}`
+                }
+            }
+        };
+        return {
+            content: [{ type: 'text', text: await renderToolText(pi, 'web_fetch', result) }],
+            details: result,
+            isError: true
+        };
+    }
+    async function guardHeadlessResponse(url) {
+        const result = {
+            status: 'error',
+            url,
+            metadata: {
+                method: 'headless',
+                cacheHit: false
+            },
+            error: postWebExploreGuardError,
+            presentation: {
+                mode: 'compact',
+                views: {
+                    compact: `Fetch failed: ${postWebExploreGuardError.message}`
+                }
+            }
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: await renderToolText(pi, 'web_fetch_headless', result)
+                }
+            ],
+            details: result,
+            isError: true
+        };
+    }
     pi.on('before_agent_start', async (event) => {
+        webExploreUsedInCurrentFlow = false;
         return {
             systemPrompt: `${event.systemPrompt}\n\n` +
                 'For web research questions that require finding and comparing multiple sources, prefer web_explore. ' +
@@ -25,9 +122,12 @@ export default function extension(pi) {
             query: Type.String({ description: 'Search query.' })
         }),
         async execute(_toolCallId, params) {
+            if (webExploreUsedInCurrentFlow) {
+                return guardSearchResponse();
+            }
             const result = await webSearch({ query: params.query });
             return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                content: [{ type: 'text', text: await renderToolText(pi, 'web_search', result) }],
                 details: result,
                 isError: result.status === 'error'
             };
@@ -41,9 +141,12 @@ export default function extension(pi) {
             url: Type.String({ description: 'HTTP or HTTPS URL to fetch.' })
         }),
         async execute(_toolCallId, params) {
+            if (webExploreUsedInCurrentFlow) {
+                return guardFetchResponse(params.url);
+            }
             const result = await webFetch({ url: params.url });
             return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                content: [{ type: 'text', text: await renderToolText(pi, 'web_fetch', result) }],
                 details: result,
                 isError: result.status === 'error'
             };
@@ -57,9 +160,12 @@ export default function extension(pi) {
             url: Type.String({ description: 'HTTP or HTTPS URL to fetch in headless mode.' })
         }),
         async execute(_toolCallId, params) {
+            if (webExploreUsedInCurrentFlow) {
+                return guardHeadlessResponse(params.url);
+            }
             const result = await webFetchHeadless({ url: params.url });
             return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                content: [{ type: 'text', text: await renderToolText(pi, 'web_fetch_headless', result) }],
                 details: result,
                 isError: result.status === 'error'
             };
@@ -74,11 +180,14 @@ export default function extension(pi) {
         }),
         async execute(_toolCallId, params) {
             const result = await webExplore({ query: params.query });
+            if (result.status === 'ok') {
+                webExploreUsedInCurrentFlow = true;
+            }
             return {
                 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/presentation/config-store.d.ts

@@ -0,0 +1,23 @@
+import type { PresentationConfig, PresentationConfigOverride, PresentationScope } from './types.js';
+export type PresentationConfigStoreOptions = {
+    homeDir?: string;
+    projectDir?: string;
+};
+export type PresentationConfigLayer = {
+    path: string;
+    exists: boolean;
+    rawConfig?: PresentationConfigOverride;
+    error?: string;
+};
+export type LoadedPresentationConfig = {
+    global: PresentationConfigLayer;
+    project: PresentationConfigLayer;
+    effectiveConfig: PresentationConfig;
+};
+export declare function getPresentationConfigPaths(options?: PresentationConfigStoreOptions): {
+    globalPath: string;
+    projectPath: string;
+};
+export declare function loadPresentationConfigLayers(options?: PresentationConfigStoreOptions): Promise<LoadedPresentationConfig>;
+export declare function savePresentationConfigScope(options: PresentationConfigStoreOptions, scope: PresentationScope, config: PresentationConfigOverride): Promise<void>;
+export declare function resetPresentationConfigScope(options: PresentationConfigStoreOptions, scope: PresentationScope): Promise<void>;