✨ 实现 Agent 内置工具：web_fetch、web_search、ask_user、agent、task 管理

新增 8 个开箱即用的内置工具，为 Agent 提供基础能力层：

- web_fetch: 抓取网页/JSON，Offscreen DOM 解析提取正文
- web_search: DuckDuckGo HTML 搜索 + Google Custom Search API
- ask_user: 向用户提问并等待回复，5 分钟超时
- agent: 启动子代理执行独立子任务，排除 ask_user/agent 防止嵌套
- create_task/get_task/update_task/list_tasks: 会话内任务跟踪

基础设施：
- Offscreen HTML 提取器（DOM 解析去骨架 + 搜索结果解析）
- 搜索引擎配置 repo（chrome.storage）
- ChatStreamEvent 新增 ask_user/sub_agent_event 类型
- System prompt 添加内置工具说明
- AskUserBlock UI 组件（提问展示 + 输入回复）

Author: CodFrm

src/app/service/agent/system_prompt.ts

@@ -42,7 +42,16 @@ Detect when you are stuck and stop early:
 - State what you will do before each action. Keep it to one short sentence.
 - When a task is blocked, explain the specific reason and what the user can do about it.
 - Keep responses concise — do not over-explain routine operations.
-- When reporting extracted data or results, format them clearly (use lists or structured text).`;
+- When reporting extracted data or results, format them clearly (use lists or structured text).
+
+## Built-in Tools
+
+You have direct access to these tools (no skill loading needed):
+- **web_fetch**: Fetch and extract content from a URL (HTML auto-extracted to readable text, JSON returned directly). Use for reading web pages, APIs, or downloading text content.
+- **web_search**: Search the web for information. Returns results with title, URL, and snippet.
+- **ask_user**: Ask the user a question and wait for their response. Use when you need clarification or a decision.
+- **agent**: Spawn a sub-agent for complex independent subtasks. The sub-agent has its own context and can use web_fetch, web_search, task tools, skills, and MCP tools. It cannot interact with the user directly.
+- **create_task / get_task / update_task / list_tasks**: Track multi-step work within this conversation. Tasks are in-memory only (not persisted across conversations).`;
 
 // Skill 摘要提示词模板
 export const SKILL_SUFFIX_HEADER = `---

src/app/service/agent/tools/ask_user.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi } from "vitest";
+import { createAskUserTool } from "./ask_user";
+import type { ChatStreamEvent } from "@App/app/service/agent/types";
+
+describe("ask_user", () => {
+  it("should send ask_user event and resolve when answer is provided", async () => {
+    const events: ChatStreamEvent[] = [];
+    const sendEvent = (event: ChatStreamEvent) => events.push(event);
+    const resolvers = new Map<string, (answer: string) => void>();
+
+    const { executor } = createAskUserTool(sendEvent, resolvers);
+
+    // Start execution (will block until resolved)
+    const resultPromise = executor.execute({ question: "What color?" });
+
+    // Verify event was sent
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe("ask_user");
+    const askEvent = events[0] as Extract<ChatStreamEvent, { type: "ask_user" }>;
+    expect(askEvent.question).toBe("What color?");
+
+    // Resolve the question
+    expect(resolvers.size).toBe(1);
+    const [askId, resolve] = Array.from(resolvers.entries())[0];
+    resolve("Blue");
+
+    const result = await resultPromise;
+    expect(JSON.parse(result as string)).toEqual({ answer: "Blue" });
+    expect(resolvers.size).toBe(0);
+  });
+
+  it("should throw if question is missing", async () => {
+    const sendEvent = vi.fn();
+    const resolvers = new Map<string, (answer: string) => void>();
+    const { executor } = createAskUserTool(sendEvent, resolvers);
+
+    await expect(executor.execute({})).rejects.toThrow("question is required");
+  });
+
+  it("should timeout after 5 minutes", async () => {
+    vi.useFakeTimers();
+    const sendEvent = vi.fn();
+    const resolvers = new Map<string, (answer: string) => void>();
+
+    const { executor } = createAskUserTool(sendEvent, resolvers);
+    const resultPromise = executor.execute({ question: "Waiting..." });
+
+    // Advance time past timeout
+    vi.advanceTimersByTime(5 * 60 * 1000 + 1);
+
+    await expect(resultPromise).rejects.toThrow("User did not respond within 5 minutes");
+    expect(resolvers.size).toBe(0);
+
+    vi.useRealTimers();
+  });
+
+  it("should generate unique ask IDs", async () => {
+    const events: ChatStreamEvent[] = [];
+    const sendEvent = (event: ChatStreamEvent) => events.push(event);
+    const resolvers = new Map<string, (answer: string) => void>();
+
+    const { executor } = createAskUserTool(sendEvent, resolvers);
+
+    // Start two asks
+    const p1 = executor.execute({ question: "Q1" });
+    const p2 = executor.execute({ question: "Q2" });
+
+    expect(events).toHaveLength(2);
+    const id1 = (events[0] as Extract<ChatStreamEvent, { type: "ask_user" }>).id;
+    const id2 = (events[1] as Extract<ChatStreamEvent, { type: "ask_user" }>).id;
+    expect(id1).not.toBe(id2);
+
+    // Resolve both
+    for (const [id, resolve] of resolvers) {
+      resolve("answer");
+    }
+    await Promise.all([p1, p2]);
+  });
+});

src/app/service/agent/tools/ask_user.ts

@@ -0,0 +1,55 @@
+import type { ToolDefinition, ChatStreamEvent } from "@App/app/service/agent/types";
+import type { ToolExecutor } from "@App/app/service/agent/tool_registry";
+
+export const ASK_USER_DEFINITION: ToolDefinition = {
+  name: "ask_user",
+  description:
+    "Ask the user a question and wait for their response. Use this when you need clarification, a decision, or user input before proceeding. The user will see the question in the chat UI and can type a response.",
+  parameters: {
+    type: "object",
+    properties: {
+      question: { type: "string", description: "The question to ask the user" },
+    },
+    required: ["question"],
+  },
+};
+
+// 5 分钟超时
+const ASK_USER_TIMEOUT_MS = 5 * 60 * 1000;
+
+export function createAskUserTool(
+  sendEvent: (event: ChatStreamEvent) => void,
+  resolvers: Map<string, (answer: string) => void>
+): { definition: ToolDefinition; executor: ToolExecutor } {
+  let askCounter = 0;
+
+  const executor: ToolExecutor = {
+    execute: async (args: Record<string, unknown>) => {
+      const question = args.question as string;
+      if (!question) {
+        throw new Error("question is required");
+      }
+
+      const askId = `ask_${Date.now()}_${++askCounter}`;
+
+      // 通知 UI 显示提问
+      sendEvent({ type: "ask_user", id: askId, question });
+
+      // 等待用户回复
+      return new Promise<string>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          resolvers.delete(askId);
+          reject(new Error("User did not respond within 5 minutes"));
+        }, ASK_USER_TIMEOUT_MS);
+
+        resolvers.set(askId, (answer: string) => {
+          clearTimeout(timer);
+          resolvers.delete(askId);
+          resolve(JSON.stringify({ answer }));
+        });
+      });
+    },
+  };
+
+  return { definition: ASK_USER_DEFINITION, executor };
+}

src/app/service/agent/tools/search_config.ts

@@ -0,0 +1,26 @@
+export type SearchEngineConfig = {
+  engine: "duckduckgo" | "google_custom";
+  googleApiKey?: string;
+  googleCseId?: string;
+};
+
+const STORAGE_KEY = "agent_search_config";
+
+const DEFAULT_CONFIG: SearchEngineConfig = {
+  engine: "duckduckgo",
+};
+
+export class SearchConfigRepo {
+  async getConfig(): Promise<SearchEngineConfig> {
+    try {
+      const result = await chrome.storage.local.get(STORAGE_KEY);
+      return result[STORAGE_KEY] || DEFAULT_CONFIG;
+    } catch {
+      return DEFAULT_CONFIG;
+    }
+  }
+
+  async saveConfig(config: SearchEngineConfig): Promise<void> {
+    await chrome.storage.local.set({ [STORAGE_KEY]: config });
+  }
+}

src/app/service/agent/tools/sub_agent.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect, vi } from "vitest";
+import { createSubAgentTool } from "./sub_agent";
+
+describe("sub_agent", () => {
+  it("should call runSubAgent with correct parameters", async () => {
+    const mockRunSubAgent = vi.fn().mockResolvedValue("Sub-agent result");
+
+    const { definition, executor } = createSubAgentTool({ runSubAgent: mockRunSubAgent });
+
+    expect(definition.name).toBe("agent");
+
+    const result = await executor.execute({ prompt: "Search for X", description: "Searching X" });
+
+    expect(mockRunSubAgent).toHaveBeenCalledWith("Search for X", "Searching X");
+    expect(result).toBe("Sub-agent result");
+  });
+
+  it("should use default description if not provided", async () => {
+    const mockRunSubAgent = vi.fn().mockResolvedValue("done");
+    const { executor } = createSubAgentTool({ runSubAgent: mockRunSubAgent });
+
+    await executor.execute({ prompt: "Do something" });
+    expect(mockRunSubAgent).toHaveBeenCalledWith("Do something", "Sub-agent task");
+  });
+
+  it("should throw if prompt is missing", async () => {
+    const mockRunSubAgent = vi.fn();
+    const { executor } = createSubAgentTool({ runSubAgent: mockRunSubAgent });
+
+    await expect(executor.execute({})).rejects.toThrow("prompt is required");
+    expect(mockRunSubAgent).not.toHaveBeenCalled();
+  });
+
+  it("should propagate errors from runSubAgent", async () => {
+    const mockRunSubAgent = vi.fn().mockRejectedValue(new Error("Agent failed"));
+    const { executor } = createSubAgentTool({ runSubAgent: mockRunSubAgent });
+
+    await expect(executor.execute({ prompt: "fail" })).rejects.toThrow("Agent failed");
+  });
+});

src/app/service/agent/tools/sub_agent.ts

@@ -0,0 +1,42 @@
+import type { ToolDefinition } from "@App/app/service/agent/types";
+import type { ToolExecutor } from "@App/app/service/agent/tool_registry";
+
+export const SUB_AGENT_DEFINITION: ToolDefinition = {
+  name: "agent",
+  description:
+    "Spawn a sub-agent to handle a complex, independent subtask. The sub-agent has its own conversation context and can use web_fetch, web_search, task tools, skills, and MCP tools. Use this for tasks that can be done independently without user interaction.",
+  parameters: {
+    type: "object",
+    properties: {
+      prompt: {
+        type: "string",
+        description: "The task description for the sub-agent. Be specific about what you need.",
+      },
+      description: {
+        type: "string",
+        description: "A short (3-5 word) description of what the sub-agent will do, shown in the UI.",
+      },
+    },
+    required: ["prompt", "description"],
+  },
+};
+
+export function createSubAgentTool(params: {
+  runSubAgent: (prompt: string, description: string) => Promise<string>;
+}): { definition: ToolDefinition; executor: ToolExecutor } {
+  const executor: ToolExecutor = {
+    execute: async (args: Record<string, unknown>) => {
+      const prompt = args.prompt as string;
+      const description = (args.description as string) || "Sub-agent task";
+
+      if (!prompt) {
+        throw new Error("prompt is required");
+      }
+
+      const result = await params.runSubAgent(prompt, description);
+      return result;
+    },
+  };
+
+  return { definition: SUB_AGENT_DEFINITION, executor };
+}

src/app/service/agent/tools/task_tools.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import { createTaskTools } from "./task_tools";
+
+describe("task_tools", () => {
+  it("should create 4 tools", () => {
+    const { tools } = createTaskTools();
+    expect(tools).toHaveLength(4);
+    const names = tools.map((t) => t.definition.name);
+    expect(names).toEqual(["create_task", "get_task", "update_task", "list_tasks"]);
+  });
+
+  it("create_task should create a task with auto-incremented ID", async () => {
+    const { tools } = createTaskTools();
+    const create = tools.find((t) => t.definition.name === "create_task")!;
+
+    const result1 = JSON.parse((await create.executor.execute({ subject: "Task 1" })) as string);
+    expect(result1).toEqual({ id: "1", subject: "Task 1", status: "pending" });
+
+    const result2 = JSON.parse(
+      (await create.executor.execute({ subject: "Task 2", description: "Details" })) as string
+    );
+    expect(result2).toEqual({ id: "2", subject: "Task 2", description: "Details", status: "pending" });
+  });
+
+  it("get_task should return task or throw", async () => {
+    const { tools } = createTaskTools();
+    const create = tools.find((t) => t.definition.name === "create_task")!;
+    const get = tools.find((t) => t.definition.name === "get_task")!;
+
+    await create.executor.execute({ subject: "Test" });
+    const result = JSON.parse((await get.executor.execute({ task_id: "1" })) as string);
+    expect(result.subject).toBe("Test");
+
+    await expect(get.executor.execute({ task_id: "999" })).rejects.toThrow('Task "999" not found');
+  });
+
+  it("update_task should update fields", async () => {
+    const { tools } = createTaskTools();
+    const create = tools.find((t) => t.definition.name === "create_task")!;
+    const update = tools.find((t) => t.definition.name === "update_task")!;
+
+    await create.executor.execute({ subject: "Original" });
+
+    const result = JSON.parse(
+      (await update.executor.execute({ task_id: "1", status: "in_progress", subject: "Updated" })) as string
+    );
+    expect(result.status).toBe("in_progress");
+    expect(result.subject).toBe("Updated");
+  });
+
+  it("update_task should throw for non-existent task", async () => {
+    const { tools } = createTaskTools();
+    const update = tools.find((t) => t.definition.name === "update_task")!;
+    await expect(update.executor.execute({ task_id: "1" })).rejects.toThrow();
+  });
+
+  it("list_tasks should return all tasks summary", async () => {
+    const { tools } = createTaskTools();
+    const create = tools.find((t) => t.definition.name === "create_task")!;
+    const list = tools.find((t) => t.definition.name === "list_tasks")!;
+
+    await create.executor.execute({ subject: "A" });
+    await create.executor.execute({ subject: "B" });
+
+    const result = JSON.parse((await list.executor.execute({})) as string);
+    expect(result).toHaveLength(2);
+    expect(result[0]).toEqual({ id: "1", subject: "A", status: "pending" });
+    expect(result[1]).toEqual({ id: "2", subject: "B", status: "pending" });
+  });
+
+  it("list_tasks should return empty array initially", async () => {
+    const { tools } = createTaskTools();
+    const list = tools.find((t) => t.definition.name === "list_tasks")!;
+    const result = JSON.parse((await list.executor.execute({})) as string);
+    expect(result).toEqual([]);
+  });
+
+  it("update_task should allow clearing description with empty string", async () => {
+    const { tools } = createTaskTools();
+    const create = tools.find((t) => t.definition.name === "create_task")!;
+    const update = tools.find((t) => t.definition.name === "update_task")!;
+
+    await create.executor.execute({ subject: "Test", description: "Some desc" });
+
+    const result = JSON.parse(
+      (await update.executor.execute({ task_id: "1", description: "" })) as string
+    );
+    expect(result.description).toBe("");
+  });
+
+  it("update_task with only task_id should not change anything", async () => {
+    const { tools } = createTaskTools();
+    const create = tools.find((t) => t.definition.name === "create_task")!;
+    const update = tools.find((t) => t.definition.name === "update_task")!;
+
+    await create.executor.execute({ subject: "Original", description: "Desc" });
+
+    const result = JSON.parse(
+      (await update.executor.execute({ task_id: "1" })) as string
+    );
+    expect(result.subject).toBe("Original");
+    expect(result.description).toBe("Desc");
+    expect(result.status).toBe("pending");
+  });
+
+  it("create_task without description should not include it in result", async () => {
+    const { tools } = createTaskTools();
+    const create = tools.find((t) => t.definition.name === "create_task")!;
+
+    const result = JSON.parse((await create.executor.execute({ subject: "No desc" })) as string);
+    expect(result.description).toBeUndefined();
+  });
+
+  it("tasks map should be independent per createTaskTools call", async () => {
+    const instance1 = createTaskTools();
+    const instance2 = createTaskTools();
+
+    const create1 = instance1.tools.find((t) => t.definition.name === "create_task")!;
+    const list2 = instance2.tools.find((t) => t.definition.name === "list_tasks")!;
+
+    await create1.executor.execute({ subject: "Only in instance1" });
+
+    const result = JSON.parse((await list2.executor.execute({})) as string);
+    expect(result).toEqual([]);
+    expect(instance1.tasks.size).toBe(1);
+    expect(instance2.tasks.size).toBe(0);
+  });
+});