hoomanjs 1.16.1 → 1.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoomanjs",
-  "version": "1.16.1",
+  "version": "1.17.1",
   "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/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/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";
 
@@ -52,15 +53,9 @@ export async function create(
   const ltm = config.tools.ltm.enabled
     ? createLongTermMemoryStore(config)
     : null;
-  const skills = config.tools.skills.enabled
-    ? (await createSkillsPrompt(registry)).content
-    : "";
-  const prefixed = config.tools.mcp.enabled
-    ? await mcp.manager.listPrefixedTools()
-    : [];
-  const append = config.tools.mcp.enabled
-    ? await mcp.manager.listServerInstructions()
-    : [];
+  const skills = (await createSkillsPrompt(registry)).content;
+  const prefixed = await mcp.manager.listPrefixedTools();
+  const append = await mcp.manager.listServerInstructions();
   const prompt = [system.content, meta.systemPrompt, ...append, skills]
     .filter((x) => !!x)
     .join(SECTION_BREAK);
@@ -73,6 +68,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/mcp/manager.ts

@@ -15,16 +15,11 @@ export const HOOMAN_CHANNEL_PERMISSION = "hooman/channel/permission";
 const HOOMAN_CHANNEL_PERMISSION_METHOD = `notifications/${HOOMAN_CHANNEL_PERMISSION}`;
 
 export type ChannelMessageMeta = {
-  server: string;
-  channel: string;
-  method: string;
-  params: unknown;
+  subscription: ChannelSubscription;
   source?: string;
-  identity: {
-    user?: string;
-    session?: string;
-    thread?: string;
-  };
+  user?: string;
+  session?: string;
+  thread?: string;
 };
 
 export type ChannelMessage = {
@@ -325,7 +320,7 @@ export class Manager {
           params?: unknown;
         }) => {
           const { method, params } = notification;
-          const prompt = this.toChannelPrompt(method, params);
+          const prompt = this.toChannelPrompt(params);
           if (!prompt) {
             return;
           }
@@ -335,16 +330,11 @@ export class Manager {
             prompt,
             attachments,
             meta: {
-              server,
-              channel,
-              method,
-              params,
+              subscription: { server, channel },
               source: readSourceValue(params),
-              identity: {
-                user: readPathValue(params, user),
-                session: readPathValue(params, session),
-                thread: readPathValue(params, thread),
-              },
+              user: readPathValue(params, user),
+              session: readPathValue(params, session),
+              thread: readPathValue(params, thread),
             },
           });
         };
@@ -463,20 +453,39 @@ export class Manager {
     }
   }
 
-  private toChannelPrompt(method: string, params?: unknown): string {
+  private toChannelPrompt(params?: unknown): string {
+    const parts = [];
+
     if (
       params &&
       typeof params === "object" &&
       "content" in params &&
       typeof params.content === "string"
     ) {
-      return params.content.trim();
+      parts.push(params.content.trim());
     }
 
-    try {
-      return JSON.stringify(params).trim();
-    } catch {
-      return String(params).trim();
+    if (
+      params &&
+      typeof params === "object" &&
+      "attachments" in params &&
+      Array.isArray(params.attachments) &&
+      params.attachments.length > 0
+    ) {
+      parts.push("User sent attachments.");
     }
+
+    if (
+      params &&
+      typeof params === "object" &&
+      "event" in params &&
+      typeof params.event === "object"
+    ) {
+      parts.push(
+        "Raw event data:\n```json\n" + JSON.stringify(params.event) + "\n```",
+      );
+    }
+
+    return parts.filter(Boolean).join("\n").trim();
   }
 }

package/src/core/prompts/environment.ts

@@ -12,6 +12,8 @@ type EnvironmentPromptContext = {
   osVersion: string;
   shell: string;
   isGitRepo: boolean;
+  currentDateTime: string;
+  timeZone: string;
 };
 
 function detectPlatform(): string {
@@ -50,13 +52,20 @@ function detectGitRepo(startDir: string): boolean {
   }
 }
 
+function detectTimeZone(): string {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone || "unknown";
+}
+
 export function getEnvironmentPromptContext(): EnvironmentPromptContext {
   const cwd = process.cwd();
+  const now = new Date();
   return {
     cwd,
     platform: detectPlatform(),
     osVersion: detectOsVersion(),
     shell: detectShell(),
     isGitRepo: detectGitRepo(cwd),
+    currentDateTime: now.toString(),
+    timeZone: detectTimeZone(),
   };
 }

package/src/core/prompts/static/environment.md

@@ -7,9 +7,11 @@ You are running in the following runtime environment:
 - Shell: `{{ environment.shell }}`
 - OS version: `{{ environment.osVersion }}`
 - Is git repository: `{{ environment.isGitRepo }}`
+- Current date/time: `{{ environment.currentDateTime }}`
+- Time zone: `{{ environment.timeZone }}`
 
 ### How To Use This
 
 - Use this information to choose correct path handling, shell syntax, and platform-specific behavior
-- Treat this section as runtime context, not real-time clock data
-- If the task needs the current date or time, call `get_current_time` instead of inferring from this section
+- Treat this section as runtime context captured when the prompt was built
+- If the task needs precise current time during a later turn, call `get_current_time`

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",
@@ -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));
+      },
+    }),
+  ];
+}

package/src/daemon/index.ts

@@ -32,23 +32,23 @@ function resolveSessionId(
   message: ChannelMessage,
   fallback?: string,
 ): string | undefined {
-  const raw = message.meta.identity.session?.trim() || fallback;
+  const raw = message.meta.session?.trim() || fallback;
   if (!raw) return undefined;
   // Namespace per `server:channel` so the same chat id coming from two
   // different MCP servers (or two channels on the same server) never collide.
-  return `${message.meta.server}:${message.meta.channel}:${raw}`;
+  return `${message.meta.subscription.server}:${message.meta.subscription.channel}:${raw}`;
 }
 
 function resolveUserId(
   message: ChannelMessage,
   session?: string,
 ): string | undefined {
-  const raw = message.meta.identity.user?.trim();
+  const raw = message.meta.user?.trim();
   if (!raw) return session;
   // Same user id across different servers is not the same human, so scope
   // user ids by server. Channel is intentionally omitted so long-term memory
   // can stay consistent for a user across rooms within one server.
-  return `${message.meta.server}:${raw}`;
+  return `${message.meta.subscription.server}:${raw}`;
 }
 
 function formatSubscriptions(
@@ -91,7 +91,7 @@ export async function main(options: RunDaemonOptions): Promise<void> {
 
   const [queue, stop] = await createQueue(
     async (message: ChannelMessage) => {
-      const tag = `${message.meta.server}:${message.meta.channel}`;
+      const tag = `${message.meta.subscription.server}:${message.meta.subscription.channel}`;
       const session = resolveSessionId(message, options.session);
       const user = resolveUserId(message, session);
 
@@ -103,18 +103,12 @@ export async function main(options: RunDaemonOptions): Promise<void> {
       options.agent.appState.set("userId", user);
       options.agent.appState.set("sessionId", session);
       const origin = {
-        server: message.meta.server,
-        channel: message.meta.channel,
+        server: message.meta.subscription.server,
+        channel: message.meta.subscription.channel,
         ...(message.meta.source ? { source: message.meta.source } : {}),
-        ...(message.meta.identity.user
-          ? { user: message.meta.identity.user }
-          : {}),
-        ...(message.meta.identity.session
-          ? { session: message.meta.identity.session }
-          : {}),
-        ...(message.meta.identity.thread
-          ? { thread: message.meta.identity.thread }
-          : {}),
+        ...(message.meta.user ? { user: message.meta.user } : {}),
+        ...(message.meta.session ? { session: message.meta.session } : {}),
+        ...(message.meta.thread ? { thread: message.meta.thread } : {}),
       };
       options.agent.appState.set("origin", {
         ...origin,
@@ -143,7 +137,7 @@ export async function main(options: RunDaemonOptions): Promise<void> {
     channels,
     (message) => {
       debug(
-        `received notification → ${message.meta.server}:${message.meta.channel}`,
+        `received notification → ${message.meta.subscription.server}:${message.meta.subscription.channel}`,
       );
       void queue.push(message);
     },