minimal-agent 0.18.10 → 0.18.12

package/src/tools/webfetch/webfetch.ts

@@ -6,27 +6,29 @@
  *
  *  输入：
  *    url    必填，要获取内容的 URL
+ *    snapshot_id / offset / max_chars / query 用于稳定续读与搜索
  *    prompt 可选，旧版兼容字段，运行时忽略
  *
  *  输出：
- *    { bytes, code, codeText, result, durationMs, url }
+ *    完整快照引用、字符范围、下一段游标与本次正文窗口
  *
  *  流程：
  *    1. URL 验证（合法格式、2000字符以内、无凭据）
  *    2. fetch（保持 HTTP(S) 协议，超时 60s）
  *    3. 检测跨 host 重定向，返回提示而非自动跟随
  *    4. HTML → Markdown（turndown）；非 HTML 原样返回
- *    5. 输出截断到 30K chars（超长内容直接截断）
+ *    5. 完整正文保存为本机会话快照，按字符游标读取或搜索
  * ============================================================
  */
 
 import { z } from 'zod';
 
-import type { Tool, ToolResult } from '../../types.js';
+import type { Tool, ToolResult, ToolCallContext } from '../../types.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { isPreapprovedDomain } from './preapproved.js';
 import { readHttpBody } from '../shared/httpBody.js';
+import { loadPageSnapshot, savePageSnapshot, pageSnapshotPath, pageWindow, type PageSnapshot } from './pageSnapshot.js';
 
 // ---------------- 1. 常量 ----------------
 const MAX_URL_LENGTH = 2000;
@@ -76,16 +78,18 @@ function cleanCache(): void {
 // ---------------- 3. Zod 输入 schema ----------------
 const inputSchema = z.object({
   url: z.string().describe('要获取内容的 URL'),
+  snapshot_id: z.string().regex(/^[a-f0-9]{64}$/).optional().describe('续读时使用上次返回的快照 ID，保证读取同一版本。'),
+  offset: z.number().int().nonnegative().optional().describe('0-based UTF-16 字符位置；使用 next_offset 续读，不是行号。'),
+  max_chars: z.number().int().min(1000).max(1_000_000).optional().describe('本次正文字符预算，Runtime 按剩余上下文收紧。'),
+  query: z.string().min(1).max(500).optional().describe('在完整快照中从 offset 开始查找精确文本（区分大小写，非正则），返回命中处正文。'),
   /** @deprecated Accepted for callers compiled against the legacy contract. */
   prompt: z.string().optional(),
 });
 type WebFetchInput = z.infer<typeof inputSchema>;
 
-// Model-visible v2 contract. WebFetch returns the page body and does not run a
+// Model-visible snapshot contract. WebFetch returns the page body and does not run a
 // hidden extraction model; the runtime schema still accepts legacy `prompt`.
-const parameters = toToolParameters(z.object({
-  url: z.string().describe('要读取正文的已知 URL'),
-}));
+const parameters = toToolParameters(inputSchema.omit({ prompt: true }));
 
 // ---------------- 4. Description ----------------
 const description = `Reads the full text content of a known URL without opening a browser.
@@ -95,8 +99,11 @@ const description = `Reads the full text content of a known URL without opening
 - It does not discover sources, authenticate, click, upload, or operate an interactive page.
 - HTTP and HTTPS URLs are fetched as supplied, including local development servers.
 - When a URL redirects to a different host, returns a warning with the redirect URL.
-- This tool is read-only and does not modify any files.
-- Very large results may be truncated with an explicit marker.
+- Read-only with respect to the source/workspace; complete extracted text is saved in a private local runtime snapshot.
+- Results are windows, not the whole page. Continue with the same url + snapshot_id + next_offset until next_offset=null. Use query for exact-text search anywhere in the snapshot.
+- max_chars can request larger windows for large-context models; the runtime may reduce the per-call budget.
+- A complete snapshot means the fetched/extracted body, not authenticated or JavaScript-rendered content. Do not claim unread ranges were inspected.
+- Conversion failures return clearly labeled raw HTML. If dynamic content is missing, use available browser tools; do not repeat the same window or invent missing content.
 - ⚠️ IMPORTANT: This tool WILL FAIL for authenticated or private URLs.
   Do not claim access to private content when the current tool catalog does not
   contain an authenticated integration for that service.
@@ -234,140 +241,66 @@ async function htmlToMarkdown(html: string): Promise<string> {
 async function call(
   input: WebFetchInput,
   signal?: AbortSignal,
+  context: ToolCallContext = {},
 ): Promise<ToolResult> {
   if (signal?.aborted) return { ok: false, error: '请求被中断' };
-  const { url } = input;
-  const start = Date.now();
-  const cacheKey = url;
-
-  let targetHostname: string;
+  const valid = validateURL(input.url);
+  if (!valid.ok) return { ok: false, error: valid.error };
+  if ((input.offset ?? 0) > 0 && !input.snapshot_id)
+    return { ok: false, error: '续读需要 snapshot_id；先读取 URL 获取稳定快照，避免拼接不同版本。' };
+  const budget = context.reserveReadChars?.(input.max_chars) ?? input.max_chars ?? DEFAULT_MAX_RESULT_SIZE_CHARS;
+  if (budget < 1000) return { ok: false, error: '本批读取预算已用完，请处理已有结果或压缩上下文后续读。' };
   try {
-    targetHostname = new URL(url).hostname;
-  } catch {
-    targetHostname = '';
-  }
-  const preapproved = isPreapprovedDomain(targetHostname);
-
-  // 检查缓存
-  const cached = URL_CACHE.get(cacheKey);
-  if (cached && Date.now() - cached.fetchedAt <= CACHE_TTL_MS) {
-    let content = cached.content;
-    const contentType = cached.contentType;
-
-    if (contentType.includes('text/html')) {
-      try {
-        content = await htmlToMarkdown(content);
-      } catch (e) {
-        console.warn(`turndown 失败: ${(e as Error).message}`);
+    let page: PageSnapshot;
+    let status = '';
+    if (input.snapshot_id) {
+      page = await loadPageSnapshot(input.snapshot_id, input.url, context);
+    } else {
+      const cached = URL_CACHE.get(input.url);
+      const hit = cached && Date.now() - cached.fetchedAt <= CACHE_TTL_MS;
+      const fetched = hit ? { type: 'success' as const, ...cached } : await fetchURL(input.url, signal ?? new AbortController().signal);
+      if (fetched.type === 'error') return { ok: false, error: fetched.error };
+      if (fetched.type === 'redirect') return { ok: true, content:
+        `【重定向检测】\n原始 URL: ${fetched.originalUrl}\n重定向到: ${fetched.redirectUrl}\n状态: ${fetched.statusCode}\n请使用重定向后的 URL 再次调用 WebFetch 工具。` };
+      const fetchedAt = hit ? cached.fetchedAt : Date.now();
+      if (!hit) {
+        URL_CACHE.set(input.url, { ...fetched, fetchedAt });
+        cleanCache();
       }
+      let text = fetched.content;
+      let format = 'text';
+      if (fetched.contentType.includes('text/html')) {
+        try { text = await htmlToMarkdown(text); format = 'markdown'; }
+        catch { format = 'raw-html (正文转换失败，保留原始 HTML)'; }
+      }
+      page = { url: input.url, text, format, fetchedAt };
+      status = `状态: ${fetched.code} ${fetched.codeText}${hit ? ' (缓存命中)' : ''}\n`;
     }
-
-    const formattedSize = cached.bytes < 1024
-      ? `${cached.bytes} B`
-      : cached.bytes < 1024 * 1024
-        ? `${(cached.bytes / 1024).toFixed(1)} KB`
-        : `${(cached.bytes / 1024 / 1024).toFixed(1)} MB`;
-
-    const domainNote = preapproved
+    signal?.throwIfAborted();
+    const snapshot = input.snapshot_id
+      ? { id: input.snapshot_id, path: pageSnapshotPath(input.snapshot_id, context) }
+      : await savePageSnapshot(page, context);
+    signal?.throwIfAborted();
+    const window = pageWindow(page.text, input.offset ?? 0, budget, input.query);
+    const domain = isPreapprovedDomain(valid.parsed.hostname)
       ? '[网络访问：预批准域名]'
       : '[网络访问：普通域名；请按来源本身评估证据质量]';
-
-    const output = `【WebFetch 结果】
-URL: ${url}
-状态: ${cached.code} ${cached.codeText}
-大小: ${formattedSize}
-耗时: 0.00s (缓存命中)
-${domainNote}
-[📦 来自缓存（15分钟 TTL）]
-
---- 内容 ---
-${content}`;
-
-    let final = output;
-    if (final.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
-      final = final.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) + `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
-    }
-
-    return { ok: true, content: final };
+    return { ok: true, policy: { highValue: true, reclaimable: false, boundedWindow: true,
+      archiveRef: snapshot.path, originalChars: page.text.length }, content: `【WebFetch 结果】
+URL: ${page.url}
+${status}${domain}
+snapshot_id: ${snapshot.id}
+snapshot_complete: true (完整抓取正文，不代表动态页面内容完整)
+format: ${page.format}
+total_chars: ${page.text.length}
+range: [${window.start}, ${window.end})
+next_offset: ${window.next ?? 'null'}
+完整正文文件: ${snapshot.path}
+${window.found ? '' : '未找到指定文本（精确匹配，区分大小写）。\n'}--- 内容 ---
+${window.text}` };
+  } catch (error) {
+    return { ok: false, error: `网页快照读取失败：${(error as Error).message}。未返回不完整正文；请重试原 URL 或检查本地存储。` };
   }
-
-  // 1. fetch
-  const fetched = await fetchURL(url, signal ?? new AbortController().signal);
-  const durationMs = Date.now() - start;
-
-  if (fetched.type === 'redirect') {
-    const statusText =
-      fetched.statusCode === 301 ? 'Moved Permanently' :
-      fetched.statusCode === 308 ? 'Permanent Redirect' :
-      fetched.statusCode === 307 ? 'Temporary Redirect' : 'Found';
-
-    return {
-      ok: true,
-      content: `【重定向检测】
-
-原始 URL: ${fetched.originalUrl}
-重定向到: ${fetched.redirectUrl}
-状态: ${fetched.statusCode} ${statusText}
-
-请使用重定向后的 URL 再次调用 WebFetch 工具。`,
-    };
-  }
-
-  if (fetched.type === 'error') {
-    return { ok: false, error: fetched.error };
-  }
-
-  let { content, bytes, code, codeText, contentType } = fetched;
-
-  // 写入缓存
-  URL_CACHE.set(cacheKey, {
-    bytes,
-    code,
-    codeText,
-    content,
-    contentType,
-    fetchedAt: Date.now(),
-  });
-  cleanCache();
-
-  // 2. HTML → Markdown
-  if (contentType.includes('text/html')) {
-    try {
-      content = await htmlToMarkdown(content);
-    } catch (e) {
-      console.warn(`turndown 失败: ${(e as Error).message}`);
-    }
-  }
-
-  // 3. 内容直接返回（超长内容在这里直接截断）
-  // 4. 追加 metadata
-  const formattedSize = bytes < 1024
-    ? `${bytes} B`
-    : bytes < 1024 * 1024
-      ? `${(bytes / 1024).toFixed(1)} KB`
-      : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-
-  const domainNote = preapproved
-    ? '[网络访问：预批准域名]'
-    : '[网络访问：普通域名；请按来源本身评估证据质量]';
-
-  const output = `【WebFetch 结果】
-URL: ${url}
-状态: ${code} ${codeText}
-大小: ${formattedSize}
-耗时: ${(durationMs / 1000).toFixed(2)}s
-${domainNote}
-
---- 内容 ---
-${content}`;
-
-  // 5. 截断
-  let final = output;
-  if (final.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
-    final = final.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) + `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
-  }
-
-  return { ok: true, content: final };
 }
 
 // ---------------- 7. 导出 ----------------
@@ -378,7 +311,8 @@ export const webfetchTool: Tool<WebFetchInput> = {
   parameters,
   isReadOnly: true,
   isConcurrencySafe: true,
-  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  maxResultSizeChars: 1_010_000,
   interruptBehavior: () => 'cancel',
   call,
+  callWithContext: (input, signal, context) => call(input, signal, context),
 };

package/src/types.ts

@@ -397,6 +397,9 @@ export interface AdvisorCheckpointMetadata extends AdvisorVersions {
 
 export interface AdvisorConsultationMetadata extends AdvisorVersions {
   kind: 'advisor_consultation';
+  /** Host-recorded trigger, distinct from who emitted the tool call. Absent in old history. */
+  triggerSource?: 'checkpoint' | 'model';
+  triggerReason?: string;
   consultationId: string;
   checkpoint: AdvisorCheckpoint;
   checkpointKey: string;
@@ -477,6 +480,9 @@ export type ToolResultMetadata =
 export interface ToolResultPolicy {
   reclaimable: boolean;
   highValue: boolean;
+  /** Tool already budgeted a window backed by a complete local snapshot.
+   * Keep this window inline: re-archiving would invalidate its visible cursor. */
+  boundedWindow?: boolean;
   archiveRef?: string;
   originalChars?: number;
 }
@@ -570,6 +576,8 @@ export type ToolResult = { problem?: ToolProblemOutcome; observation?: ReadObser
  * 避免按工具名写特判分支。
  */
 export interface ToolCallContext {
+  /** Run-local host initialization shared with Advisor; never a model argument. */
+  advisorConsultation?: AdvisorConsultationMetadata;
   /** Shared per-model-response read allowance; reservations happen before IO. */
   reserveReadChars?: (requested?: number) => number;
   /** Host presentation only; cannot grant tools to a delegated agent. */