@pellux/goodvibes-agent 0.1.23 → 0.1.25

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to GoodVibes Agent will be recorded here.
 
+## 0.1.25 - 2026-05-31
+
+- cba5f6d Harden Agent find tool policy
+
+## 0.1.24 - 2026-05-31
+
+- 2375df3 Bound web search tool policy
+
 ## 0.1.23 - 2026-05-31
 
 - 18d7381 Harden analyze and registry tool policy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "private": false,
   "description": "Near-fork GoodVibes operator assistant with the GoodVibes TUI shell, renderer, input, fullscreen workspace, and daemon-connected Agent product brain.",
   "type": "module",

package/src/tools/agent-find-policy.ts

@@ -0,0 +1,124 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+
+type FindQueryArgs = {
+  readonly follow_symlinks?: unknown;
+  readonly include_hidden?: unknown;
+  readonly respect_gitignore?: unknown;
+  readonly [key: string]: unknown;
+};
+
+type FindOutputArgs = {
+  readonly format?: unknown;
+  readonly [key: string]: unknown;
+};
+
+type FindToolArgs = {
+  readonly queries?: unknown;
+  readonly output?: unknown;
+  readonly parallel?: unknown;
+  readonly [key: string]: unknown;
+};
+
+const READ_ONLY_FIND_OUTPUT_FORMATS = [
+  'count_only',
+  'files_only',
+  'locations',
+  'matches',
+  'context',
+  'with_stats',
+  'signatures',
+] as const;
+
+const READ_ONLY_FIND_OUTPUT_FORMAT_SET = new Set<string>(READ_ONLY_FIND_OUTPUT_FORMATS);
+
+const FIND_POLICY_DENIAL = [
+  'GoodVibes Agent only exposes serial, project-root, gitignore-respecting search from the main conversation.',
+  'Hidden-file scans, symlink traversal, gitignore bypass, broad file previews, full symbol dumps, and parallel search are disabled here.',
+  'Use explicit Agent CLI/slash commands or GoodVibes TUI delegation for deeper local inspection.',
+].join(' ');
+
+export const AGENT_READ_ONLY_FIND_OUTPUT_FORMATS = READ_ONLY_FIND_OUTPUT_FORMATS;
+export const AGENT_FIND_POLICY_DENIAL_MESSAGE = FIND_POLICY_DENIAL;
+
+export function wrapFindToolForAgentPolicy(tool: Tool): void {
+  narrowFindToolDefinitionForAgentPolicy(tool);
+  const originalExecute = tool.execute.bind(tool);
+  tool.execute = async (args) => {
+    const findArgs = args as FindToolArgs;
+    const denial = validateFindToolInvocationForAgentPolicy(findArgs);
+    if (denial) return { success: false, error: denial };
+    return originalExecute(normalizeFindToolInvocationForAgentPolicy(findArgs) as Parameters<Tool['execute']>[0]);
+  };
+}
+
+export function validateFindToolInvocationForAgentPolicy(args: FindToolArgs): string | null {
+  if (args.parallel === true) return FIND_POLICY_DENIAL;
+
+  if (Array.isArray(args.queries)) {
+    for (const query of args.queries) {
+      if (!isRecord(query)) continue;
+      const queryArgs = query as FindQueryArgs;
+      if (queryArgs.follow_symlinks === true) return FIND_POLICY_DENIAL;
+      if (queryArgs.include_hidden === true) return FIND_POLICY_DENIAL;
+      if (queryArgs.respect_gitignore === false) return FIND_POLICY_DENIAL;
+    }
+  }
+
+  if (isRecord(args.output)) {
+    const output = args.output as FindOutputArgs;
+    if (typeof output.format === 'string' && !READ_ONLY_FIND_OUTPUT_FORMAT_SET.has(output.format)) {
+      return FIND_POLICY_DENIAL;
+    }
+  }
+
+  return null;
+}
+
+export function normalizeFindToolInvocationForAgentPolicy(args: FindToolArgs): FindToolArgs {
+  return {
+    ...args,
+    parallel: false,
+  };
+}
+
+function narrowFindToolDefinitionForAgentPolicy(tool: Tool): void {
+  tool.definition.description = [
+    'Search the project for GoodVibes Agent using serial, gitignore-respecting read-only queries.',
+    'Hidden-file scans, symlink traversal, gitignore bypass, broad previews, full symbol dumps, and parallel search are disabled in the main conversation.',
+  ].join(' ');
+  tool.definition.sideEffects = ['read_fs'];
+  tool.definition.concurrency = 'serial';
+
+  const properties = tool.definition.parameters.properties;
+  if (!isRecord(properties)) return;
+  delete properties.parallel;
+
+  const queries = properties.queries;
+  if (isRecord(queries)) {
+    const itemSchema = queries.items;
+    if (isRecord(itemSchema)) {
+      const queryProperties = itemSchema.properties;
+      if (isRecord(queryProperties)) {
+        delete queryProperties.follow_symlinks;
+        delete queryProperties.include_hidden;
+        delete queryProperties.respect_gitignore;
+      }
+    }
+  }
+
+  const output = properties.output;
+  if (!isRecord(output)) return;
+  const outputProperties = output.properties;
+  if (!isRecord(outputProperties)) return;
+
+  const format = outputProperties.format;
+  if (isRecord(format)) {
+    format.enum = [...READ_ONLY_FIND_OUTPUT_FORMATS];
+    format.description = 'Bounded output format allowed by GoodVibes Agent main-conversation search policy.';
+  }
+  delete outputProperties.preview_lines;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/tools/agent-web-search-policy.ts

@@ -0,0 +1,112 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+
+type WebSearchToolArgs = {
+  readonly maxResults?: unknown;
+  readonly verbosity?: unknown;
+  readonly safeSearch?: unknown;
+  readonly includeEvidence?: unknown;
+  readonly evidenceTopN?: unknown;
+  readonly evidenceExtract?: unknown;
+  readonly [key: string]: unknown;
+};
+
+const READ_ONLY_WEB_SEARCH_VERBOSITIES = ['urls_only', 'titles', 'snippets', 'evidence'] as const;
+const READ_ONLY_WEB_SEARCH_EVIDENCE_EXTRACTS = [
+  'text',
+  'markdown',
+  'readable',
+  'code_blocks',
+  'links',
+  'metadata',
+  'tables',
+] as const;
+
+const READ_ONLY_WEB_SEARCH_VERBOSITY_SET = new Set<string>(READ_ONLY_WEB_SEARCH_VERBOSITIES);
+const READ_ONLY_WEB_SEARCH_EVIDENCE_EXTRACT_SET = new Set<string>(READ_ONLY_WEB_SEARCH_EVIDENCE_EXTRACTS);
+
+const MAX_WEB_SEARCH_RESULTS = 10;
+const MAX_WEB_SEARCH_EVIDENCE_TOP_N = 3;
+
+const WEB_SEARCH_POLICY_DENIAL = [
+  'GoodVibes Agent only exposes bounded, read-only web research from the main conversation.',
+  'Full-page/raw/summary evidence extraction, safe-search off, and high-fanout searches are disabled here.',
+  'Use explicit Agent CLI/slash commands or an approval-backed workflow for broader external research.',
+].join(' ');
+
+export const AGENT_READ_ONLY_WEB_SEARCH_VERBOSITIES = READ_ONLY_WEB_SEARCH_VERBOSITIES;
+export const AGENT_READ_ONLY_WEB_SEARCH_EVIDENCE_EXTRACTS = READ_ONLY_WEB_SEARCH_EVIDENCE_EXTRACTS;
+export const AGENT_MAX_WEB_SEARCH_RESULTS = MAX_WEB_SEARCH_RESULTS;
+export const AGENT_MAX_WEB_SEARCH_EVIDENCE_TOP_N = MAX_WEB_SEARCH_EVIDENCE_TOP_N;
+export const AGENT_WEB_SEARCH_POLICY_DENIAL_MESSAGE = WEB_SEARCH_POLICY_DENIAL;
+
+export function wrapWebSearchToolForAgentPolicy(tool: Tool): void {
+  narrowWebSearchToolDefinitionForAgentPolicy(tool);
+  const originalExecute = tool.execute.bind(tool);
+  tool.execute = async (args) => {
+    const denial = validateWebSearchToolInvocationForAgentPolicy(args as WebSearchToolArgs);
+    if (denial) return { success: false, error: denial };
+    return originalExecute(normalizeWebSearchToolInvocationForAgentPolicy(args as WebSearchToolArgs) as Parameters<Tool['execute']>[0]);
+  };
+}
+
+export function validateWebSearchToolInvocationForAgentPolicy(args: WebSearchToolArgs): string | null {
+  if (typeof args.maxResults === 'number' && args.maxResults > MAX_WEB_SEARCH_RESULTS) return WEB_SEARCH_POLICY_DENIAL;
+  if (typeof args.evidenceTopN === 'number' && args.evidenceTopN > MAX_WEB_SEARCH_EVIDENCE_TOP_N) return WEB_SEARCH_POLICY_DENIAL;
+  if (args.safeSearch === 'off') return WEB_SEARCH_POLICY_DENIAL;
+  if (typeof args.verbosity === 'string' && !READ_ONLY_WEB_SEARCH_VERBOSITY_SET.has(args.verbosity)) {
+    return WEB_SEARCH_POLICY_DENIAL;
+  }
+  if (
+    typeof args.evidenceExtract === 'string'
+    && !READ_ONLY_WEB_SEARCH_EVIDENCE_EXTRACT_SET.has(args.evidenceExtract)
+  ) {
+    return WEB_SEARCH_POLICY_DENIAL;
+  }
+  return null;
+}
+
+export function normalizeWebSearchToolInvocationForAgentPolicy(args: WebSearchToolArgs): WebSearchToolArgs {
+  return {
+    ...args,
+    safeSearch: typeof args.safeSearch === 'string' ? args.safeSearch : 'moderate',
+  };
+}
+
+function narrowWebSearchToolDefinitionForAgentPolicy(tool: Tool): void {
+  tool.definition.description = [
+    'Run bounded, read-only web research for GoodVibes Agent.',
+    'Full-page/raw/summary extraction, safe-search off, and high-fanout searches are disabled in the main conversation.',
+  ].join(' ');
+  tool.definition.sideEffects = ['network'];
+
+  const properties = tool.definition.parameters.properties;
+  if (!isRecord(properties)) return;
+
+  const verbosity = properties.verbosity;
+  if (isRecord(verbosity)) {
+    verbosity.enum = [...READ_ONLY_WEB_SEARCH_VERBOSITIES];
+    verbosity.description = 'Bounded result verbosity allowed by GoodVibes Agent main-conversation policy.';
+  }
+
+  const evidenceExtract = properties.evidenceExtract;
+  if (isRecord(evidenceExtract)) {
+    evidenceExtract.enum = [...READ_ONLY_WEB_SEARCH_EVIDENCE_EXTRACTS];
+    evidenceExtract.description = 'Bounded evidence extraction modes allowed by GoodVibes Agent main-conversation policy.';
+  }
+
+  const maxResults = properties.maxResults;
+  if (isRecord(maxResults)) {
+    maxResults.maximum = MAX_WEB_SEARCH_RESULTS;
+    maxResults.description = 'Maximum ranked results returned by GoodVibes Agent main-conversation web research.';
+  }
+
+  const evidenceTopN = properties.evidenceTopN;
+  if (isRecord(evidenceTopN)) {
+    evidenceTopN.maximum = MAX_WEB_SEARCH_EVIDENCE_TOP_N;
+    evidenceTopN.description = 'Maximum top results fetched for evidence by GoodVibes Agent main-conversation web research.';
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/tools/wrfc-agent-guard.ts

@@ -4,6 +4,8 @@ import {
   wrapAnalyzeToolForAgentPolicy,
   wrapRegistryToolForAgentPolicy,
 } from './agent-analysis-registry-policy.ts';
+import { wrapFindToolForAgentPolicy } from './agent-find-policy.ts';
+import { wrapWebSearchToolForAgentPolicy } from './agent-web-search-policy.ts';
 
 type AgentToolArgs = {
   readonly mode?: unknown;
@@ -230,6 +232,10 @@ export function installAgentToolPolicyGuard(registry: ToolRegistry, options: Age
       wrapAnalyzeToolForAgentPolicy(tool);
     } else if (tool.definition.name === 'registry') {
       wrapRegistryToolForAgentPolicy(tool);
+    } else if (tool.definition.name === 'find') {
+      wrapFindToolForAgentPolicy(tool);
+    } else if (tool.definition.name === 'web_search') {
+      wrapWebSearchToolForAgentPolicy(tool);
     } else if (tool.definition.name === 'control') {
       wrapModeRestrictedToolForAgentPolicy(tool, {
         allowedModes: READ_ONLY_CONTROL_TOOL_MODES,
@@ -553,6 +559,25 @@ export {
   wrapRegistryToolForAgentPolicy,
 } from './agent-analysis-registry-policy.ts';
 
+export {
+  AGENT_FIND_POLICY_DENIAL_MESSAGE,
+  AGENT_READ_ONLY_FIND_OUTPUT_FORMATS,
+  normalizeFindToolInvocationForAgentPolicy,
+  validateFindToolInvocationForAgentPolicy,
+  wrapFindToolForAgentPolicy,
+} from './agent-find-policy.ts';
+
+export {
+  AGENT_MAX_WEB_SEARCH_EVIDENCE_TOP_N,
+  AGENT_MAX_WEB_SEARCH_RESULTS,
+  AGENT_READ_ONLY_WEB_SEARCH_EVIDENCE_EXTRACTS,
+  AGENT_READ_ONLY_WEB_SEARCH_VERBOSITIES,
+  AGENT_WEB_SEARCH_POLICY_DENIAL_MESSAGE,
+  normalizeWebSearchToolInvocationForAgentPolicy,
+  validateWebSearchToolInvocationForAgentPolicy,
+  wrapWebSearchToolForAgentPolicy,
+} from './agent-web-search-policy.ts';
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '0.1.23';
+let _version = '0.1.25';
 let _sdkVersion = '0.33.35';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8')) as {