minimal-agent 0.10.0 → 0.12.0

package/src/tools/websearch/websearch.ts

@@ -0,0 +1,292 @@
+/**
+ * ============================================================
+ *  src/tools/websearch.ts —— WebSearch 工具（联网搜索）
+ * ------------------------------------------------------------
+ *  底层调用 Tavily Search API（https://tavily.com/）。
+ *  发请求带退避重试（见下「4b. 退避重试」）：并发突发 + dev/免费 key 被前端切 socket
+ *  的瞬态不再直接当失败喂回 LLM。次数由 TAVILY_MAX_RETRIES 控（默认 3）。
+ *
+ *  为什么选 Tavily：
+ *    - LLM 友好：返回结构化 JSON，自带 content 摘要；不用我们再去抓 HTML
+ *    - 接口简单：一个 POST + JSON body 搞定，不用 OAuth / 翻墙
+ *    - 免费额度：每月 1000 次足够学习用
+ *
+ *  Key 配置：
+ *    在项目根 .env 里加：
+ *      TAVILY_API_KEY=
+ *    没设的话，工具会返回友好错误（不影响 agent 启动）。
+ *
+ *  输入：
+ *    query         必填，搜索关键词
+ *    max_results   可选，默认 5（Tavily 上限 20）
+ *    search_depth  可选 'basic' | 'advanced'，默认 basic
+ *    topic         可选 'general' | 'news'，默认 general
+ *
+ *  输出：
+ *    每条结果一段：
+ *      [1] 标题
+ *      URL: https://...
+ *      内容摘要（content）
+ *    如有 answer 字段（advanced 才返回），先列在最上面。
+ * ============================================================
+ */
+
+import { z } from 'zod';
+
+import type { Tool, ToolResult } from '../../types.js';
+import { configService } from '../../config/configService.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+  query: z
+    .string()
+    .min(1, '必须提供搜索关键词')
+    .max(400, '搜索关键词太长（>400 字）')
+    .describe('搜索关键词，建议自然语言描述需要查的信息'),
+  max_results: z
+    .number()
+    .int()
+    .min(1)
+    .max(20)
+    .optional()
+    .describe('返回结果数量，1-20，默认 5'),
+  search_depth: z
+    .enum(['basic', 'advanced'])
+    .optional()
+    .describe('basic 快但浅；advanced 慢但深（含 answer 摘要），默认 basic'),
+  topic: z
+    .enum(['general', 'news'])
+    .optional()
+    .describe('general=通用网页；news=偏新闻源；默认 general'),
+});
+type WebSearchInput = z.infer<typeof inputSchema>;
+
+// ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
+const parameters = toToolParameters(inputSchema);
+
+// ---------------- 3. Description（给 LLM 看的工具说明） ----------------
+const description = `Searches the public web through Tavily and returns structured source candidates.
+- Use it to discover sources, verify current information, compare multiple sources, or locate current documentation.
+- It does not open or operate a browser. Use returned URLs with WebFetch when full source text is needed.
+- Results contain title, URL and a text snippet. They are discovery evidence, not a substitute for reading a high-value source in full.
+- Keep each query focused on one sub-question. When another search is needed, change the keywords, source, or angle instead of repeating the same query.
+- Add an explicit date or year only when recency matters; stable concepts and exact names should remain exact.
+- \`search_depth: "advanced"\` is slower but can return a synthesized answer; \`topic: "news"\` favors news sources.
+- Requires a configured Tavily API key.`;
+
+// ---------------- 4. Tavily 响应类型（仅取我们用到的字段） ----------------
+interface TavilyResult {
+  title: string;
+  url: string;
+  content: string;
+  score?: number;
+  published_date?: string;
+}
+interface TavilyResponse {
+  query?: string;
+  answer?: string;
+  results?: TavilyResult[];
+}
+
+// ---------------- 4b. 退避重试 ----------------
+//
+// 为什么需要（与单发 fetch 零重试的旧行为对比）：WebSearch 是 isConcurrencySafe 工具，
+// 主循环把同一轮的多个 WebSearch 调用 **并行**发火（loop.ts，Promise.all）。研究类
+// prompt 又常让模型「围绕 3–6 个子问题分别检索」——于是一瞬间 3~6 条连接同时打向
+// 同一个 Tavily key。dev / 免费 ティア 的并发/速率上限被触发时，CDN 前端常**直接切断
+// socket** 而非返回干净的 429（错误落进 fetch 的 catch：「socket connection closed
+// unexpectedly」）。旧代码单发 fetch、零重试，这类瞬态会被直接当失败喂回 LLM ——
+// 表现为「突然连续搜索失败，但单发检索仍通」。
+//
+// 对策与 llm/client.ts 的自适应退避同思想（本地、有界、带抖动）：
+//   可重试：fetch 抛错（socket 切断/超时）+ HTTP 429 + 5xx（尊重 Retry-After）。
+//   不重试：用户中断（signal）、其它 4xx（401 key 错 / 400 参数错，重试无意义）、
+//           JSON 解析失败（body 已到、重发大概率同样坏）。
+//   次数：默认 3 次重试（共 4 次尝试），可用 TAVILY_MAX_RETRIES 覆盖。
+//   抖动：±15% 把并发重试**散开**，避免落 socket 的几条同时再殺到、又一起被切。
+
+const TAVILY_ENDPOINT = 'https://api.tavily.com/search';
+
+function tavilyMaxRetries(): number {
+  const n = Number(process.env.TAVILY_MAX_RETRIES);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 3;
+}
+
+/** 退避时长（ms）：优先 Retry-After；否则指数 500·2^n 封顶 8s，再叠 ±15% 抖动。 */
+function backoffDelayMs(attempt: number, retryAfterMs?: number): number {
+  if (retryAfterMs && retryAfterMs > 0) return Math.min(retryAfterMs, 15000);
+  const capped = Math.min(500 * 2 ** attempt, 8000);
+  return Math.round(capped * (0.85 + Math.random() * 0.3));
+}
+
+/** Retry-After 头解析（秒数 或 HTTP-date）→ ms；无法解析返回 undefined。 */
+function parseRetryAfter(h: string | null): number | undefined {
+  if (!h) return undefined;
+  const secs = Number(h);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
+  const at = Date.parse(h);
+  return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now());
+}
+
+/** 可中断退避：signal abort 时立即 resolve（让外层据 signal 收口，不在这里抛）。 */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/** 发 Tavily 请求并按上述策略重试。成功返回已解析的 data，失败返回 friendly error。 */
+async function fetchTavilyWithRetry(
+  body: unknown,
+  signal?: AbortSignal,
+): Promise<{ ok: true; data: TavilyResponse } | { ok: false; error: string }> {
+  const maxRetries = tavilyMaxRetries();
+  let lastErr = '';
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (signal?.aborted) return { ok: false, error: '搜索已被中断' };
+
+    let res: Response;
+    try {
+      res = await fetch(TAVILY_ENDPOINT, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal,
+      });
+    } catch (e) {
+      if (signal?.aborted) return { ok: false, error: '搜索已被中断' };
+      lastErr = `调用 Tavily 失败（网络）：${(e as Error).message}`;
+      if (attempt < maxRetries) {
+        await sleep(backoffDelayMs(attempt), signal);
+        continue;
+      }
+      break;
+    }
+
+    // 429 / 5xx：服务端瞬态（限流 / 过载 / 切 socket 后偶发的 5xx）→ 可重试
+    if (res.status === 429 || res.status >= 500) {
+      const text = await res.text().catch(() => '');
+      lastErr = `Tavily HTTP ${res.status}：${text.slice(0, 300)}`;
+      if (attempt < maxRetries) {
+        const wait = backoffDelayMs(attempt, parseRetryAfter(res.headers.get('retry-after')));
+        await sleep(wait, signal);
+        continue;
+      }
+      break;
+    }
+
+    // 其它 4xx（401 key 无效 / 400 参数错…）：重试无意义，立即返回
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      return { ok: false, error: `Tavily HTTP ${res.status}：${text.slice(0, 500)}` };
+    }
+
+    // 解析 JSON（坏响应不重试——body 已到、重发大概率同样坏）
+    try {
+      const data = (await res.json()) as TavilyResponse;
+      return { ok: true, data };
+    } catch (e) {
+      return { ok: false, error: `Tavily 响应不是合法 JSON：${(e as Error).message}` };
+    }
+  }
+
+  return {
+    ok: false,
+    error:
+      `${lastErr}（已重试 ${maxRetries} 次仍失败——并发突发下 dev/免费 key 易被前端切 socket；` +
+      `可减少同轮并发检索数、调大 TAVILY_MAX_RETRIES，或升级 Tavily key）`,
+  };
+}
+
+// ---------------- 5. call() ----------------
+async function call(
+  input: WebSearchInput,
+  signal?: AbortSignal,
+  getApiKey: () => Promise<string | undefined> = async () => (await configService.tool('webSearch'))?.apiKey,
+): Promise<ToolResult> {
+  // 5a. 取 key
+  const apiKey = await getApiKey();
+  if (!apiKey) {
+    return {
+      ok: false,
+      error:
+        'WebSearch 不可用：尚未配置 Tavily API Key。\n' +
+        '请在 KakadeAI 设置 → 工具 → 联网搜索中配置，或在 env 模式提供 TAVILY_API_KEY。',
+    };
+  }
+
+  const body = {
+    api_key: apiKey,
+    // Preserve the exact research query. The prompt layer adds a date only
+    // when recency matters; unconditional mutation hurts exact names,
+    // historical topics, and stable technical documentation.
+    query: input.query,
+    max_results: input.max_results ?? 5,
+    search_depth: input.search_depth ?? 'basic',
+    topic: input.topic ?? 'general',
+    // 让 advanced 模式自动给 answer；basic 不会有
+    include_answer: input.search_depth === 'advanced',
+  };
+
+  // 5c. 发请求（带退避重试，吸收 dev/免费 key 在并发突发下的 socket 切断 + 429/5xx）
+  const fetched = await fetchTavilyWithRetry(body, signal);
+  if (!fetched.ok) return { ok: false, error: fetched.error };
+  const data = fetched.data;
+
+  // 5d. 取结果
+  const results = data.results ?? [];
+  if (results.length === 0) {
+    return {
+      ok: true,
+      content: `(no results for "${input.query}")`,
+    };
+  }
+
+  // 5e. 拼输出
+  const parts: string[] = [];
+  if (data.answer) {
+    parts.push(`【综合回答】\n${data.answer}\n`);
+  }
+  parts.push(`【共 ${results.length} 条结果】`);
+  results.forEach((r, i) => {
+    const date = r.published_date ? `（${r.published_date}）` : '';
+    parts.push(
+      `\n[${i + 1}] ${r.title}${date}\nURL: ${r.url}\n${(r.content ?? '').trim()}`,
+    );
+  });
+
+  let content = parts.join('\n');
+  if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+    content =
+      content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
+      `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
+  }
+
+  return { ok: true, content };
+}
+
+// ---------------- 6. 导出 ----------------
+export function createWebSearchTool(
+  getApiKey: () => Promise<string | undefined> = async () => (await configService.tool('webSearch'))?.apiKey,
+): Tool<WebSearchInput> {
+  return {
+    name: 'WebSearch', description, inputSchema, parameters, isReadOnly: true,
+    isConcurrencySafe: true, maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    interruptBehavior: () => 'cancel',
+    call: (input, signal) => call(input, signal, getApiKey),
+  };
+}
+
+export const webSearchTool = createWebSearchTool();

package/src/tools/worktree/sessionWorktree.js

@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { join } from 'node:path';
+import { readRuntimeJson, sessionRuntimeDir, writeRuntimeJson, } from '../../session/runtimeStore.js';
+import { applyAgentWorktree, commitWorktreeChanges, createAgentWorktree, hasWorktreeChanges, removeAgentWorktree, } from '../agent/worktree.js';
+const enterSchema = z.object({
+    name: z
+        .string()
+        .regex(/^[a-zA-Z0-9._-]{1,48}$/)
+        .optional(),
+});
+const exitSchema = z.object({ action: z.enum(['apply', 'keep', 'discard']) });
+async function persist(ctx, state) {
+    await writeRuntimeJson(join(sessionRuntimeDir(ctx), 'worktree.json'), {
+        active: state ?? null,
+    });
+}
+export async function hydrateSessionWorktree(ctx) {
+    if (!ctx.sessionState || ctx.sessionState.activeWorktree)
+        return;
+    const saved = await readRuntimeJson(join(sessionRuntimeDir(ctx), 'worktree.json'), {});
+    if (saved.active)
+        ctx.sessionState.activeWorktree = saved.active;
+}
+async function enter(input, ctx) {
+    const state = ctx.sessionState;
+    if (!state)
+        return { ok: false, error: 'EnterWorktree 需要会话状态' };
+    if (state.activeWorktree)
+        return {
+            ok: true,
+            content: `当前已在 worktree ${state.activeWorktree.path}`,
+        };
+    const slug = `session-${input.name ?? randomUUID().slice(0, 8)}`;
+    const wt = await createAgentWorktree(slug, ctx.cwd);
+    if (!wt.ok)
+        return wt;
+    state.activeWorktree = {
+        id: slug,
+        path: wt.path,
+        branch: wt.branch,
+        baseSha: wt.baseSha,
+        gitRoot: wt.gitRoot,
+    };
+    await persist(ctx, state.activeWorktree);
+    return {
+        ok: true,
+        content: `已进入主 Agent 隔离 worktree：${wt.path}\n分支：${wt.branch}\n后续工具调用立即使用该目录。`,
+    };
+}
+async function exit(input, ctx) {
+    const state = ctx.sessionState, wt = state?.activeWorktree;
+    if (!state || !wt)
+        return { ok: false, error: '当前会话没有活动 worktree' };
+    if (input.action === 'keep') {
+        state.activeWorktree = undefined;
+        await persist(ctx, undefined);
+        return {
+            ok: true,
+            content: `已退出有效 cwd，但保留 worktree：${wt.path}\n分支：${wt.branch}`,
+        };
+    }
+    const changed = await hasWorktreeChanges(wt.path, wt.baseSha);
+    if (input.action === 'discard' && changed) {
+        const committed = await commitWorktreeChanges(wt.path, `archive: preserve discarded session ${wt.id}`);
+        if (committed.ok) {
+            state.activeWorktree = undefined;
+            await persist(ctx, undefined);
+        }
+        return committed.ok
+            ? {
+                ok: true,
+                content: `检测到成果，未永久删除。已归档到分支 ${wt.branch}，worktree 保留在 ${wt.path}。`,
+            }
+            : {
+                ok: false,
+                error: `无法安全归档，worktree 保持活动：${committed.error}`,
+            };
+    }
+    if (input.action === 'discard') {
+        await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+        state.activeWorktree = undefined;
+        await persist(ctx, undefined);
+        return {
+            ok: true,
+            content: 'worktree 无改动，已通过 Git worktree 管理安全清理。',
+        };
+    }
+    const committed = await commitWorktreeChanges(wt.path, `minimal-agent: apply session ${wt.id}`);
+    if (!committed.ok)
+        return {
+            ok: false,
+            error: `提交隔离改动失败，worktree 保持活动：${committed.error}`,
+        };
+    const applied = await applyAgentWorktree(wt.gitRoot, wt.id);
+    if (!applied.ok)
+        return {
+            ok: false,
+            error: `应用检查失败，worktree 保持活动：${applied.error}`,
+        };
+    state.activeWorktree = undefined;
+    await persist(ctx, undefined);
+    return {
+        ok: true,
+        content: `已通过 git apply --check 并将变更应用到原工作区；未自动提交。`,
+    };
+}
+export const enterWorktreeTool = {
+    name: 'EnterWorktree',
+    description: 'Creates and enters a session-scoped Git worktree for the main Agent. Later tool calls use it immediately while project memory keeps the original workspace identity.',
+    inputSchema: enterSchema,
+    parameters: toToolParameters(enterSchema),
+    isReadOnly: false,
+    isConcurrencySafe: false,
+    call: async () => ({ ok: false, error: 'requires session context' }),
+    callWithContext: (i, _s, c) => enter(i, c),
+};
+export const exitWorktreeTool = {
+    name: 'ExitWorktree',
+    description: 'Leaves the current session worktree. apply checks and applies its patch to the original workspace; keep preserves it; discard never destroys uncommitted results and archives changed work.',
+    inputSchema: exitSchema,
+    parameters: toToolParameters(exitSchema),
+    isReadOnly: false,
+    isConcurrencySafe: false,
+    call: async () => ({ ok: false, error: 'requires session context' }),
+    callWithContext: (i, _s, c) => exit(i, c),
+};

package/src/tools/worktree/sessionWorktree.ts

@@ -0,0 +1,158 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import type { SessionState } from '../../session/sessionState.js';
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { join } from 'node:path';
+import {
+  readRuntimeJson,
+  sessionRuntimeDir,
+  writeRuntimeJson,
+} from '../../session/runtimeStore.js';
+import {
+  applyAgentWorktree,
+  commitWorktreeChanges,
+  createAgentWorktree,
+  hasWorktreeChanges,
+  removeAgentWorktree,
+} from '../agent/worktree.js';
+
+const enterSchema = z.object({
+  name: z
+    .string()
+    .regex(/^[a-zA-Z0-9._-]{1,48}$/)
+    .optional(),
+});
+const exitSchema = z.object({ action: z.enum(['apply', 'keep', 'discard']) });
+async function persist(
+  ctx: ToolCallContext,
+  state: SessionState['activeWorktree'],
+) {
+  await writeRuntimeJson(join(sessionRuntimeDir(ctx), 'worktree.json'), {
+    active: state ?? null,
+  });
+}
+export async function hydrateSessionWorktree(
+  ctx: ToolCallContext,
+): Promise<void> {
+  if (!ctx.sessionState || ctx.sessionState.activeWorktree) return;
+  const saved = await readRuntimeJson<{
+    active?: NonNullable<SessionState['activeWorktree']> | null;
+  }>(join(sessionRuntimeDir(ctx), 'worktree.json'), {});
+  if (saved.active) ctx.sessionState.activeWorktree = saved.active;
+}
+async function enter(
+  input: z.infer<typeof enterSchema>,
+  ctx: ToolCallContext,
+): Promise<ToolResult> {
+  const state = ctx.sessionState;
+  if (!state) return { ok: false, error: 'EnterWorktree 需要会话状态' };
+  if (state.activeWorktree)
+    return {
+      ok: true,
+      content: `当前已在 worktree ${state.activeWorktree.path}`,
+    };
+  const slug = `session-${input.name ?? randomUUID().slice(0, 8)}`;
+  const wt = await createAgentWorktree(slug, ctx.cwd);
+  if (!wt.ok) return wt;
+  state.activeWorktree = {
+    id: slug,
+    path: wt.path,
+    branch: wt.branch,
+    baseSha: wt.baseSha,
+    gitRoot: wt.gitRoot,
+  };
+  await persist(ctx, state.activeWorktree);
+  return {
+    ok: true,
+    content: `已进入主 Agent 隔离 worktree：${wt.path}\n分支：${wt.branch}\n后续工具调用立即使用该目录。`,
+  };
+}
+async function exit(
+  input: z.infer<typeof exitSchema>,
+  ctx: ToolCallContext,
+): Promise<ToolResult> {
+  const state = ctx.sessionState,
+    wt = state?.activeWorktree;
+  if (!state || !wt) return { ok: false, error: '当前会话没有活动 worktree' };
+  if (input.action === 'keep') {
+    state.activeWorktree = undefined;
+    await persist(ctx, undefined);
+    return {
+      ok: true,
+      content: `已退出有效 cwd，但保留 worktree：${wt.path}\n分支：${wt.branch}`,
+    };
+  }
+  const changed = await hasWorktreeChanges(wt.path, wt.baseSha);
+  if (input.action === 'discard' && changed) {
+    const committed = await commitWorktreeChanges(
+      wt.path,
+      `archive: preserve discarded session ${wt.id}`,
+    );
+    if (committed.ok) {
+      state.activeWorktree = undefined;
+      await persist(ctx, undefined);
+    }
+    return committed.ok
+      ? {
+          ok: true,
+          content: `检测到成果，未永久删除。已归档到分支 ${wt.branch}，worktree 保留在 ${wt.path}。`,
+        }
+      : {
+          ok: false,
+          error: `无法安全归档，worktree 保持活动：${committed.error}`,
+        };
+  }
+  if (input.action === 'discard') {
+    await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+    state.activeWorktree = undefined;
+    await persist(ctx, undefined);
+    return {
+      ok: true,
+      content: 'worktree 无改动，已通过 Git worktree 管理安全清理。',
+    };
+  }
+  const committed = await commitWorktreeChanges(
+    wt.path,
+    `minimal-agent: apply session ${wt.id}`,
+  );
+  if (!committed.ok)
+    return {
+      ok: false,
+      error: `提交隔离改动失败，worktree 保持活动：${committed.error}`,
+    };
+  const applied = await applyAgentWorktree(wt.gitRoot, wt.id);
+  if (!applied.ok)
+    return {
+      ok: false,
+      error: `应用检查失败，worktree 保持活动：${applied.error}`,
+    };
+  state.activeWorktree = undefined;
+  await persist(ctx, undefined);
+  return {
+    ok: true,
+    content: `已通过 git apply --check 并将变更应用到原工作区；未自动提交。`,
+  };
+}
+export const enterWorktreeTool: Tool<z.infer<typeof enterSchema>> = {
+  name: 'EnterWorktree',
+  description:
+    'Creates and enters a session-scoped Git worktree for the main Agent. Later tool calls use it immediately while project memory keeps the original workspace identity.',
+  inputSchema: enterSchema,
+  parameters: toToolParameters(enterSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  call: async () => ({ ok: false, error: 'requires session context' }),
+  callWithContext: (i, _s, c) => enter(i, c),
+};
+export const exitWorktreeTool: Tool<z.infer<typeof exitSchema>> = {
+  name: 'ExitWorktree',
+  description:
+    'Leaves the current session worktree. apply checks and applies its patch to the original workspace; keep preserves it; discard never destroys uncommitted results and archives changed work.',
+  inputSchema: exitSchema,
+  parameters: toToolParameters(exitSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  call: async () => ({ ok: false, error: 'requires session context' }),
+  callWithContext: (i, _s, c) => exit(i, c),
+};