hoomanjs 1.16.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoomanjs",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Hackable Bun-powered AI agent toolkit for building local CLI, ACP, MCP, and channel-driven workflows.",
   "author": {
     "name": "Vaibhav Pandey",
@@ -60,6 +60,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "^0.6.0",
     "@strands-agents/sdk": "^1.0.0-rc.3",
+    "@tavily/core": "^0.7.2",
     "chromadb": "^3.4.3",
     "cli-highlight": "^2.1.11",
     "cli-spinners": "^3.4.0",

package/src/acp/acp-agent.ts

@@ -334,6 +334,7 @@ export class AcpAgent implements AgentContract {
       agent,
       mcp: { manager },
     } = await bootstrap(
+      "acp",
       {
         userId: bootstrapUserId,
         sessionId,
@@ -432,6 +433,7 @@ export class AcpAgent implements AgentContract {
       agent,
       mcp: { manager },
     } = await bootstrap(
+      "acp",
       {
         userId: bootstrapUserId,
         sessionId: params.sessionId,

package/src/acp/utils/tool-kind.ts

@@ -22,6 +22,7 @@ const KNOWN_TOOL_KINDS = new Map<string, ToolKind>([
   ["wiki_knowledge_graph", "read"],
   ["wiki_stats", "read"],
   ["wiki_search", "search"],
+  ["web_search", "search"],
   ["think", "think"],
   ["run_agents", "other"],
   ["update_todos", "other"],

package/src/cli.ts

@@ -55,7 +55,7 @@ program
       const {
         agent,
         mcp: { manager },
-      } = await bootstrap({ sessionId }, true);
+      } = await bootstrap("default", { sessionId }, true);
       agent.addHook(
         BeforeToolCallEvent,
         createToolApprovalHandler({ yolo: Boolean(options.yolo) }),
@@ -86,7 +86,7 @@ program
         agent,
         mcp: { manager },
         registry,
-      } = await bootstrap({ sessionId }, false);
+      } = await bootstrap("default", { sessionId }, false);
 
       try {
         await chat({
@@ -129,10 +129,10 @@ program
         agent,
         mcp: { manager },
       } = await bootstrap(
+        "daemon",
         {
           sessionId: session,
           userId: session,
-          mode: "daemon",
         },
         true,
       );

package/src/configure/app.tsx

@@ -139,6 +139,7 @@ export function ConfigureApp({
       ({
         name: config.name,
         llm: config.llm,
+        search: config.search,
         prompts: config.prompts,
         tools: config.tools,
         compaction: config.compaction,
@@ -448,6 +449,81 @@ export function ConfigureApp({
         label: `Prompts • ${enabledPrompts}/${totalPrompts} enabled`,
         value: () => setScreen({ kind: "config-prompts" }),
       },
+      {
+        label: "Tools • configure enabled tools",
+        value: () => setScreen({ kind: "config-tools" }),
+      },
+      {
+        label: `Compaction ratio • ${configData.compaction.ratio}`,
+        value: () =>
+          promptValue({
+            title: "Update compaction ratio",
+            label: "Ratio",
+            initialValue: String(configData.compaction.ratio),
+            onSubmit: async (value) => {
+              const ratio = parseNumber(value, "Compaction ratio", {
+                min: 0,
+                max: 1,
+              });
+              updateConfig(
+                {
+                  compaction: {
+                    ...config.compaction,
+                    ratio,
+                  },
+                },
+                "Updated compaction ratio.",
+              );
+              setPrompt(null);
+            },
+          }),
+      },
+      {
+        label: `Compaction keep • ${configData.compaction.keep}`,
+        value: () =>
+          promptValue({
+            title: "Update compaction keep",
+            label: "Keep",
+            initialValue: String(configData.compaction.keep),
+            onSubmit: async (value) => {
+              const keep = parseNumber(value, "Compaction keep", {
+                min: 0,
+                integer: true,
+              });
+              updateConfig(
+                {
+                  compaction: {
+                    ...config.compaction,
+                    keep,
+                  },
+                },
+                "Updated compaction keep.",
+              );
+              setPrompt(null);
+            },
+          }),
+      },
+      {
+        label: "Back",
+        value: () => setScreen({ kind: "home" }),
+      },
+    ];
+
+    return (
+      <MenuScreen
+        title="Configuration"
+        description="Edit the same values loaded from ~/.hooman/config.json."
+        items={items}
+      />
+    );
+  };
+
+  const renderToolsConfigMenu = () => {
+    const items: MenuItem[] = [
+      {
+        label: `Search tool • ${configData.search.enabled ? "Enabled" : "Disabled"} • ${configData.search.provider}`,
+        value: () => setScreen({ kind: "config-search" }),
+      },
       {
         label: `Todo tool • ${configData.tools.todo.enabled ? "Enabled" : "Disabled"}`,
         value: () => {
@@ -462,7 +538,7 @@ export function ConfigureApp({
             },
             `Todo tool ${configData.tools.todo.enabled ? "disabled" : "enabled"}.`,
           );
-          setScreen({ kind: "config" });
+          setScreen({ kind: "config-tools" });
         },
       },
       {
@@ -479,7 +555,7 @@ export function ConfigureApp({
             },
             `Fetch tool ${configData.tools.fetch.enabled ? "disabled" : "enabled"}.`,
           );
-          setScreen({ kind: "config" });
+          setScreen({ kind: "config-tools" });
         },
       },
       {
@@ -496,7 +572,7 @@ export function ConfigureApp({
             },
             `Filesystem tool ${configData.tools.filesystem.enabled ? "disabled" : "enabled"}.`,
           );
-          setScreen({ kind: "config" });
+          setScreen({ kind: "config-tools" });
         },
       },
       {
@@ -513,7 +589,7 @@ export function ConfigureApp({
             },
             `Shell tool ${configData.tools.shell.enabled ? "disabled" : "enabled"}.`,
           );
-          setScreen({ kind: "config" });
+          setScreen({ kind: "config-tools" });
         },
       },
       {
@@ -530,7 +606,7 @@ export function ConfigureApp({
             },
             `Sleep tool ${configData.tools.sleep.enabled ? "disabled" : "enabled"}.`,
           );
-          setScreen({ kind: "config" });
+          setScreen({ kind: "config-tools" });
         },
       },
       {
@@ -555,7 +631,7 @@ export function ConfigureApp({
             },
             `MCP tools ${configData.tools.mcp.enabled ? "disabled" : "enabled"}.`,
           );
-          setScreen({ kind: "config" });
+          setScreen({ kind: "config-tools" });
         },
       },
       {
@@ -572,69 +648,19 @@ export function ConfigureApp({
             },
             `Skills tools ${configData.tools.skills.enabled ? "disabled" : "enabled"}.`,
           );
-          setScreen({ kind: "config" });
+          setScreen({ kind: "config-tools" });
         },
       },
-      {
-        label: `Compaction ratio • ${configData.compaction.ratio}`,
-        value: () =>
-          promptValue({
-            title: "Update compaction ratio",
-            label: "Ratio",
-            initialValue: String(configData.compaction.ratio),
-            onSubmit: async (value) => {
-              const ratio = parseNumber(value, "Compaction ratio", {
-                min: 0,
-                max: 1,
-              });
-              updateConfig(
-                {
-                  compaction: {
-                    ...config.compaction,
-                    ratio,
-                  },
-                },
-                "Updated compaction ratio.",
-              );
-              setPrompt(null);
-            },
-          }),
-      },
-      {
-        label: `Compaction keep • ${configData.compaction.keep}`,
-        value: () =>
-          promptValue({
-            title: "Update compaction keep",
-            label: "Keep",
-            initialValue: String(configData.compaction.keep),
-            onSubmit: async (value) => {
-              const keep = parseNumber(value, "Compaction keep", {
-                min: 0,
-                integer: true,
-              });
-              updateConfig(
-                {
-                  compaction: {
-                    ...config.compaction,
-                    keep,
-                  },
-                },
-                "Updated compaction keep.",
-              );
-              setPrompt(null);
-            },
-          }),
-      },
       {
         label: "Back",
-        value: () => setScreen({ kind: "home" }),
+        value: () => setScreen({ kind: "config" }),
       },
     ];
 
     return (
       <MenuScreen
-        title="Configuration"
-        description="Edit the same values loaded from ~/.hooman/config.json."
+        title="Tools"
+        description="Enable, disable, and configure built-in tools."
         items={items}
       />
     );
@@ -696,7 +722,7 @@ export function ConfigureApp({
       }),
       {
         label: "Back",
-        value: () => setScreen({ kind: "config" }),
+        value: () => setScreen({ kind: "config-tools" }),
       },
     ];
 
@@ -709,6 +735,113 @@ export function ConfigureApp({
     );
   };
 
+  const renderSearchProviderMenu = () => {
+    const items: MenuItem[] = [
+      ...(["brave", "tavily"] as const).map((provider) => ({
+        label:
+          provider === configData.search.provider
+            ? `${provider} • current`
+            : provider,
+        value: () => {
+          updateConfig(
+            {
+              search: {
+                ...config.search,
+                provider,
+              },
+            },
+            `Updated search provider to "${provider}".`,
+          );
+          setScreen({ kind: "config-search" });
+        },
+      })),
+      {
+        label: "Back",
+        value: () => setScreen({ kind: "config-search" }),
+      },
+    ];
+
+    return (
+      <MenuScreen
+        title="Search Provider"
+        description="Pick which web search provider to use."
+        items={items}
+      />
+    );
+  };
+
+  const renderSearchConfigMenu = () => {
+    const activeProvider = configData.search.provider;
+    const apiKey =
+      activeProvider === "brave"
+        ? configData.search.brave.apiKey
+        : configData.search.tavily.apiKey;
+    const redacted = compactJson(
+      maskSensitiveParamsForDisplay({ apiKey: apiKey ?? "" }),
+    );
+    const items: MenuItem[] = [
+      {
+        label: `Enabled • ${configData.search.enabled ? "On" : "Off"}`,
+        value: () => {
+          updateConfig(
+            {
+              search: {
+                ...config.search,
+                enabled: !configData.search.enabled,
+              },
+            },
+            `Search tool ${configData.search.enabled ? "disabled" : "enabled"}.`,
+          );
+          setScreen({ kind: "config-search" });
+        },
+      },
+      {
+        label: `Provider • ${configData.search.provider}`,
+        value: () => setScreen({ kind: "config-search-provider" }),
+      },
+      {
+        label: `${activeProvider} API key • ${truncate(redacted, 44)}`,
+        value: () =>
+          promptValue({
+            title: `Update ${activeProvider} API key`,
+            label: "API key",
+            initialValue: apiKey ?? "",
+            onSubmit: async (value) => {
+              const nextApiKey = value.trim();
+              if (!nextApiKey) {
+                throw new Error("API key is required.");
+              }
+              updateConfig(
+                {
+                  search: {
+                    ...config.search,
+                    [activeProvider]: {
+                      ...config.search[activeProvider],
+                      apiKey: nextApiKey,
+                    },
+                  },
+                },
+                `Updated ${activeProvider} API key.`,
+              );
+              setPrompt(null);
+            },
+          }),
+      },
+      {
+        label: "Back",
+        value: () => setScreen({ kind: "config-tools" }),
+      },
+    ];
+
+    return (
+      <MenuScreen
+        title="Search"
+        description="Configure web search provider and credentials."
+        items={items}
+      />
+    );
+  };
+
   const renderLtmConfigMenu = () => {
     const items: MenuItem[] = [
       {
@@ -793,7 +926,7 @@ export function ConfigureApp({
       },
       {
         label: "Back",
-        value: () => setScreen({ kind: "config" }),
+        value: () => setScreen({ kind: "config-tools" }),
       },
     ];
 
@@ -1171,6 +1304,12 @@ export function ConfigureApp({
         return renderProviderMenu();
       case "config-prompts":
         return renderPromptsConfigMenu();
+      case "config-tools":
+        return renderToolsConfigMenu();
+      case "config-search":
+        return renderSearchConfigMenu();
+      case "config-search-provider":
+        return renderSearchProviderMenu();
       case "config-ltm":
         return renderLtmConfigMenu();
       case "config-wiki":

package/src/configure/types.ts

@@ -12,8 +12,11 @@ export type ConfigureAppProps = {
 export type Screen =
   | { kind: "home" }
   | { kind: "config" }
+  | { kind: "config-tools" }
   | { kind: "config-provider" }
   | { kind: "config-prompts" }
+  | { kind: "config-search" }
+  | { kind: "config-search-provider" }
   | { kind: "config-ltm" }
   | { kind: "config-wiki" }
   | { kind: "mcp" }

package/src/core/agent/index.ts

@@ -28,6 +28,7 @@ import {
   createThinkingTools,
   createTimeTools,
   createWikiTools,
+  createWebSearchTools,
 } from "../tools";
 import { clearTodoState } from "../tools/todo.ts";
 
@@ -73,6 +74,7 @@ export async function create(
     ...(ltm ? createLongTermMemoryTools(ltm) : []),
     ...(config.tools.filesystem.enabled ? createFilesystemTools() : []),
     ...(config.tools.shell.enabled ? createShellTools() : []),
+    ...(config.search.enabled ? createWebSearchTools(config) : []),
     ...(config.tools.wiki.enabled ? createWikiTools(config) : []),
     ...(config.tools.mcp.enabled ? createMcpTools(mcp.config) : []),
     ...(config.tools.skills.enabled ? createSkillsTools(registry) : []),

package/src/core/agents/definitions.ts

@@ -26,6 +26,7 @@ export const BUILTIN_AGENT_CONFIGS: readonly AgentConfig[] = [
       "search_files",
       "get_file_info",
       "fetch",
+      "web_search",
       "think",
     ],
   },
@@ -40,6 +41,7 @@ export const BUILTIN_AGENT_CONFIGS: readonly AgentConfig[] = [
       "directory_tree",
       "search_files",
       "get_file_info",
+      "web_search",
       "think",
     ],
   },

package/src/core/approvals/allowed-tools.ts

@@ -30,6 +30,8 @@ export const INTERNAL_ALWAYS_ALLOWED = new Set([
   "wiki_search",
   "wiki_stats",
   "wiki_write_file",
+  // Web search
+  "web_search",
   // Long-term memory
   "archive_memory",
   "search_memory",

package/src/core/config.ts

@@ -92,6 +92,23 @@ const AgentsPartialSchema = z.object({
   concurrency: z.number().int().min(1).optional(),
 });
 
+const SearchProviderSchema = z.enum(["brave", "tavily"]);
+
+const SearchPartialSchema = z.object({
+  enabled: z.boolean().optional(),
+  provider: SearchProviderSchema.optional(),
+  brave: z
+    .object({
+      apiKey: z.string().min(1).optional(),
+    })
+    .optional(),
+  tavily: z
+    .object({
+      apiKey: z.string().min(1).optional(),
+    })
+    .optional(),
+});
+
 const ToolsPartialSchema = z.object({
   todo: ToolTogglePartialSchema.optional(),
   fetch: ToolTogglePartialSchema.optional(),
@@ -109,6 +126,7 @@ const ConfigSchema = z
   .object({
     name: z.string().min(1),
     llm: LlmSchema,
+    search: SearchPartialSchema.nullish(),
     prompts: PromptsPartialSchema.nullish(),
     tools: ToolsPartialSchema.nullish(),
     compaction: CompactionPartialSchema.nullish().transform((c) => ({
@@ -122,6 +140,16 @@ const ConfigSchema = z
     return {
       name: input.name,
       llm: input.llm,
+      search: {
+        enabled: input.search?.enabled ?? false,
+        provider: input.search?.provider ?? "brave",
+        brave: {
+          apiKey: input.search?.brave?.apiKey,
+        },
+        tavily: {
+          apiKey: input.search?.tavily?.apiKey,
+        },
+      },
       prompts: {
         behaviour: input.prompts?.behaviour ?? DEFAULT_PROMPTS.behaviour,
         communication:
@@ -189,6 +217,7 @@ export type CompactionConfig = ConfigData["compaction"];
 export type PromptsConfig = ConfigData["prompts"];
 export type LtmConfig = ConfigData["tools"]["ltm"];
 export type WikiConfig = ConfigData["tools"]["wiki"];
+export type SearchConfig = ConfigData["search"];
 export type ToolsConfig = ConfigData["tools"];
 
 const defaultConfigData = (): ConfigData => ({
@@ -198,6 +227,12 @@ const defaultConfigData = (): ConfigData => ({
     model: "gemma4:e4b",
     params: {},
   },
+  search: {
+    enabled: false,
+    provider: "brave",
+    brave: { apiKey: undefined },
+    tavily: { apiKey: undefined },
+  },
   prompts: { ...DEFAULT_PROMPTS },
   tools: {
     todo: {
@@ -263,6 +298,14 @@ export class Config {
     return this.data.llm;
   }
 
+  get search(): SearchConfig {
+    return {
+      ...this.data.search,
+      brave: { ...this.data.search.brave },
+      tavily: { ...this.data.search.tavily },
+    };
+  }
+
   get prompts(): PromptsConfig {
     return { ...this.data.prompts };
   }

package/src/core/index.ts

@@ -21,16 +21,18 @@ import {
 export type BootstrapMeta = {
   userId?: string;
   sessionId?: string;
-  mode?: "default" | "daemon";
   acp?: AcpMeta;
 };
 
+export type BootstrapMode = "default" | "daemon" | "acp";
+
 export type AcpMeta = {
   systemPrompt?: string;
   mcpServers?: NamedMcpTransport[];
 };
 
 export async function bootstrap(
+  mode: BootstrapMode,
   meta: BootstrapMeta,
   print: boolean = false,
 ): Promise<{
@@ -43,16 +45,12 @@ export async function bootstrap(
   const mcpConfig = createMcpConfig(mcpJsonPath());
   const mcpManager = createMcpManager(
     mcpConfig,
-    meta.acp !== undefined,
+    mode === "acp",
     meta.acp?.mcpServers ?? [],
   );
   const mcp = { config: mcpConfig, manager: mcpManager };
   const registry = createSkillsRegistry(basePath());
-  const system = await createSystemPrompt(
-    instructionsMdPath(),
-    config,
-    meta.mode ?? "default",
-  );
+  const system = await createSystemPrompt(instructionsMdPath(), config, mode);
   const agent = await createAgent(config, system, registry, mcp, print, {
     userId: meta?.userId ?? meta?.sessionId,
     sessionId: meta?.sessionId,

package/src/core/prompts/static/web-search.md

@@ -0,0 +1,38 @@
+## Web Search
+
+You have access to a `web_search` tool for finding relevant webpages and snippets.
+
+### When To Use It
+
+- Use `web_search` when you need current or external information not available in local context.
+- Prefer it for discovering candidate sources before reading full page content.
+- After identifying promising URLs, use `fetch` to read those pages in detail.
+
+### Input Contract
+
+Use only these inputs:
+
+- `query` (required)
+- `count` (optional)
+- `freshness` (optional: `day`, `week`, `month`, `year`)
+- `start_date` + `end_date` (optional date range, `YYYY-MM-DD`)
+- `country` (optional country code)
+- `safe_search` (optional boolean)
+
+Do not invent provider-specific parameters.
+
+### Examples
+
+- General current-information search:
+  - `{"query":"latest TypeScript 6 release notes","count":5}`
+- Recency-filtered search:
+  - `{"query":"browser rendering performance updates","freshness":"week","count":5}`
+- Country-targeted search:
+  - `{"query":"renewable energy policy updates","country":"DE","count":5}`
+- Search operators inside query:
+  - `{"query":"\"climate change\" site:ipcc.ch filetype:pdf -draft","count":5}`
+
+### Notes
+
+- `web_search` returns result pages and snippets, not full article bodies.
+- For complete page content, call `fetch` on selected result URLs.

package/src/core/prompts/system.ts

@@ -14,6 +14,7 @@ const STATIC_PROMPT_FILES = [
   "thinking.md",
   "filesystem.md",
   "fetch.md",
+  "web-search.md",
   "shell.md",
   "sleep.md",
   "daemon.md",
@@ -30,7 +31,7 @@ const HARNESS_PROMPT_FILES = [
   { key: "guardrails", file: "guardrails.md" },
 ] as const;
 
-export type SystemMode = "default" | "daemon";
+export type SystemMode = "default" | "daemon" | "acp";
 
 const SECTION_BREAK = "\n\n---\n\n";
 
@@ -61,6 +62,8 @@ export class System {
           return this.config.tools.ltm.enabled;
         case "fetch.md":
           return this.config.tools.fetch.enabled;
+        case "web-search.md":
+          return this.config.search.enabled;
         case "todo.md":
           return this.config.tools.todo.enabled;
         case "filesystem.md":

package/src/core/tools/index.ts

@@ -5,4 +5,5 @@ export { createShellTools } from "./shell.ts";
 export { createThinkingTools } from "./thinking.ts";
 export { createTimeTools } from "./time.ts";
 export { createTodoTools } from "./todo.ts";
+export { createWebSearchTools } from "./web-search.ts";
 export { createWikiTools } from "./wiki.ts";

package/src/core/tools/web-search.ts

@@ -0,0 +1,278 @@
+import { tool } from "@strands-agents/sdk";
+import type { JSONValue, ToolContext } from "@strands-agents/sdk";
+import { tavily } from "@tavily/core";
+import { z } from "zod";
+import type { Config } from "../config.ts";
+
+const BRAVE_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+const DEFAULT_TIMEOUT_SECONDS = 20;
+const DEFAULT_RESULT_COUNT = 5;
+const MAX_RESULT_COUNT = 20;
+
+const FreshnessSchema = z.enum(["day", "week", "month", "year"]);
+
+const InputSchema = z
+  .object({
+    query: z.string().min(1).max(400),
+    count: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_RESULT_COUNT)
+      .default(DEFAULT_RESULT_COUNT),
+    freshness: FreshnessSchema.optional(),
+    start_date: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/)
+      .optional(),
+    end_date: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/)
+      .optional(),
+    country: z
+      .string()
+      .regex(/^[a-z]{2}$/i)
+      .optional(),
+    safe_search: z.boolean().optional(),
+  })
+  .superRefine((input, context) => {
+    const hasStartDate = Boolean(input.start_date);
+    const hasEndDate = Boolean(input.end_date);
+    if (hasStartDate !== hasEndDate) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "start_date and end_date must be provided together.",
+      });
+    }
+    if (hasStartDate && input.freshness) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "Use either freshness or start_date/end_date, not both together.",
+      });
+    }
+  });
+
+type WebSearchInput = z.infer<typeof InputSchema>;
+
+type NormalizedResult = {
+  title: string;
+  url: string;
+  snippet: string;
+};
+
+type NormalizedOutput = {
+  provider: "brave" | "tavily";
+  query: string;
+  results: NormalizedResult[];
+  metadata: {
+    count: number;
+    freshness: WebSearchInput["freshness"] | null;
+    start_date: string | null;
+    end_date: string | null;
+    country: string | null;
+    safe_search: boolean | null;
+    returned_results: number;
+  };
+};
+
+function toJsonValue(value: unknown): JSONValue {
+  return JSON.parse(JSON.stringify(value)) as JSONValue;
+}
+
+function toBraveFreshness(input: WebSearchInput): string | undefined {
+  if (input.start_date && input.end_date) {
+    return `${input.start_date}to${input.end_date}`;
+  }
+  switch (input.freshness) {
+    case "day":
+      return "pd";
+    case "week":
+      return "pw";
+    case "month":
+      return "pm";
+    case "year":
+      return "py";
+    default:
+      return undefined;
+  }
+}
+
+function tavilyCountryCode(code: string | undefined): string | undefined {
+  if (!code) {
+    return undefined;
+  }
+  try {
+    const display = new Intl.DisplayNames(["en"], { type: "region" }).of(
+      code.toUpperCase(),
+    );
+    if (!display) {
+      return undefined;
+    }
+    return display.toLowerCase();
+  } catch {
+    return undefined;
+  }
+}
+
+function cleanString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeBraveResults(payload: unknown): NormalizedResult[] {
+  const root = payload as {
+    web?: { results?: Array<Record<string, unknown>> };
+  };
+  const results = root.web?.results;
+  if (!Array.isArray(results)) {
+    return [];
+  }
+  return results
+    .map((item) => ({
+      title: cleanString(item.title),
+      url: cleanString(item.url),
+      snippet: cleanString(item.description),
+    }))
+    .filter((item) => item.url.length > 0);
+}
+
+function normalizeTavilyResults(payload: unknown): NormalizedResult[] {
+  const root = payload as { results?: Array<Record<string, unknown>> };
+  if (!Array.isArray(root.results)) {
+    return [];
+  }
+  return root.results
+    .map((item) => ({
+      title: cleanString(item.title),
+      url: cleanString(item.url),
+      snippet: cleanString(item.content),
+    }))
+    .filter((item) => item.url.length > 0);
+}
+
+function normalizedOutput(
+  provider: "brave" | "tavily",
+  input: WebSearchInput,
+  results: NormalizedResult[],
+): NormalizedOutput {
+  return {
+    provider,
+    query: input.query,
+    results,
+    metadata: {
+      count: input.count,
+      freshness: input.freshness ?? null,
+      start_date: input.start_date ?? null,
+      end_date: input.end_date ?? null,
+      country: input.country?.toUpperCase() ?? null,
+      safe_search: input.safe_search ?? null,
+      returned_results: results.length,
+    },
+  };
+}
+
+async function searchBrave(
+  input: WebSearchInput,
+  apiKey: string,
+  signal: AbortSignal,
+): Promise<NormalizedOutput> {
+  const url = new URL(BRAVE_ENDPOINT);
+  url.searchParams.set("q", input.query);
+  url.searchParams.set("count", String(input.count));
+  if (input.country) {
+    url.searchParams.set("country", input.country.toUpperCase());
+  }
+  const freshness = toBraveFreshness(input);
+  if (freshness) {
+    url.searchParams.set("freshness", freshness);
+  }
+  if (input.safe_search !== undefined) {
+    url.searchParams.set("safesearch", input.safe_search ? "strict" : "off");
+  }
+
+  const response = await fetch(url, {
+    method: "GET",
+    signal,
+    headers: {
+      accept: "application/json",
+      "x-subscription-token": apiKey,
+    },
+  });
+  const body = await response.text();
+  if (!response.ok) {
+    throw new Error(
+      `Brave search failed (${response.status} ${response.statusText}): ${body}`,
+    );
+  }
+  const parsed = JSON.parse(body) as unknown;
+  return normalizedOutput("brave", input, normalizeBraveResults(parsed));
+}
+
+async function searchTavily(
+  input: WebSearchInput,
+  apiKey: string,
+): Promise<NormalizedOutput> {
+  const client = tavily({ apiKey }) as {
+    search: (
+      query: string,
+      options?: Record<string, unknown>,
+    ) => Promise<unknown>;
+  };
+  const options: Record<string, unknown> = {
+    max_results: input.count,
+  };
+  if (input.country) {
+    const mappedCountry = tavilyCountryCode(input.country);
+    if (mappedCountry) {
+      options.country = mappedCountry;
+    }
+  }
+  if (input.start_date && input.end_date) {
+    options.start_date = input.start_date;
+    options.end_date = input.end_date;
+  } else if (input.freshness) {
+    options.time_range = input.freshness;
+  }
+  if (input.safe_search !== undefined) {
+    options.safe_search = input.safe_search;
+  }
+
+  const response = await client.search(input.query, options);
+  return normalizedOutput("tavily", input, normalizeTavilyResults(response));
+}
+
+export function createWebSearchTools(config: Config) {
+  return [
+    tool({
+      name: "web_search",
+      description:
+        "Search the web using configured provider and return normalized results.",
+      inputSchema: InputSchema,
+      callback: async (input, context?: ToolContext) => {
+        const timeoutSignal = AbortSignal.timeout(
+          DEFAULT_TIMEOUT_SECONDS * 1000,
+        );
+        const signal = context
+          ? AbortSignal.any([timeoutSignal, context.agent.cancelSignal])
+          : timeoutSignal;
+        const provider = config.search.provider;
+        if (provider === "brave") {
+          const apiKey = config.search.brave.apiKey;
+          if (!apiKey) {
+            throw new Error(
+              "Search provider is brave but search.brave.apiKey is missing.",
+            );
+          }
+          return toJsonValue(await searchBrave(input, apiKey, signal));
+        }
+        const apiKey = config.search.tavily.apiKey;
+        if (!apiKey) {
+          throw new Error(
+            "Search provider is tavily but search.tavily.apiKey is missing.",
+          );
+        }
+        return toJsonValue(await searchTavily(input, apiKey));
+      },
+    }),
+  ];
+}