berry-agent 0.1.0-alpha.1

package/dist/web/service.js

@@ -0,0 +1,207 @@
+/**
+ * WebFetchService——三消费面共用的唯一 execute 路径（02 §4.1 席 18「两消费
+ * 面同一 execute」+ 03 §10.3 browser 件章第三消费位）。
+ *
+ * 五卫生件编排序（缺一不可、逐跳复跑）：
+ *   限流（在飞门）→ URL 解析 + 协议白名单 → 私网判定（字面 + DNS）→
+ *   重定向跟随（手动逐跳——每跳目标重跑解析/协议/私网三查，跳数触帽拒）→
+ *   字节上限（流式读取，触帽截断置 truncated 非拒）→ 归因落账（sink 注入，
+ *   ok/blocked/error 三结局全落——运行账「谁在何时取了什么」）。
+ *
+ * 超时不在本件：signal 归调用方（工具面 = 管道执行段预算；服务面 = 调用方
+ * 自带）——服务内不设时钟（可测性 + 预算单源）。
+ *
+ * 已知边界（v1 注记）：redirect:'manual' 逐跳拦截 + 请求前 DNS 全查已覆盖
+ * 模型可控的全部 URL 面；DNS 校验与实际连接的解析漂移窗（rebinding）与
+ * undici 连接级钉死挂账后续批。
+ */
+import { BaseError } from '../contracts/index.js';
+import { createInFlightGate } from './gate.js';
+import { assertPublicHost, defaultDnsResolver, parseWebUrl } from './hygiene.js';
+/** 缺省数值帽（随实机校准回填——规范不收数字，07 §1.1 只列五卫生件名目） */
+export const DEFAULT_WEB_LIMITS = {
+    maxRedirects: 5,
+    maxBytes: 1024 * 1024,
+    maxConcurrent: 4,
+};
+/** 重定向状态码集（其余 3xx 按终态返回不跟随） */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * 流式读响应体到字节帽：触帽即 cancel 流（不再拉数据）、截到恰好帽值、
+ * truncated 置真。只产原始字节——UTF-8 严格解码由调用方在快照 bytes 之后
+ * 做（解码失败也是「已读了这么多字节」的失败，归因记账不归零）。
+ */
+async function readBodyCapped(response, maxBytes) {
+    if (response.body === null) {
+        // HEAD/204 等空体形——零字节非截断
+        return { raw: new Uint8Array(0), bytes: 0, truncated: false };
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (total + value.byteLength > maxBytes) {
+            // 触帽：只收帽内余量，弃流
+            const remainder = maxBytes - total;
+            if (remainder > 0)
+                chunks.push(value.slice(0, remainder));
+            total = maxBytes;
+            truncated = true;
+            await reader.cancel().catch(() => {
+                // cancel 失败不阻断——连接由 undici 自理，数据已不再被读
+            });
+            break;
+        }
+        chunks.push(value);
+        total += value.byteLength;
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { raw: merged, bytes: total, truncated };
+}
+/** UTF-8 严格解码（截断劈尾回退剥 ≤3 字节——UTF-8 最长序列 4 字节；真非 UTF-8 各试皆红抛普通 Error——二进制内容不适用文本 fetch 面，属普通失败非卫生拦截） */
+function decodeUtf8Strict(bytes, truncated) {
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    // 未截断时全长一次即判（劈尾剥除只对截断形有意义）；截断形全长 → 剥 1..3
+    const candidates = truncated ? [0, 1, 2, 3] : [0];
+    for (const trim of candidates) {
+        try {
+            return decoder.decode(bytes.subarray(0, bytes.byteLength - trim));
+        }
+        catch {
+            // 继续下一候选
+        }
+    }
+    throw new Error('响应体非 UTF-8 文本——二进制内容不适用 fetch 工具（文本面只认 UTF-8）');
+}
+/**
+ * 服务构造：三消费面（fetch 工具 / ctx.fetch 插件消费 / browser 导航）共用
+ * 同一 service 实例即共用同一 execute 与同一在飞门。
+ */
+export function createWebFetchService(deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? ((url, init) => fetch(url, init));
+    const resolveDns = deps.resolveDns ?? defaultDnsResolver;
+    const now = deps.now ?? (() => Date.now());
+    const sink = deps.sink ?? (() => { });
+    const limits = { ...DEFAULT_WEB_LIMITS, ...deps.limits };
+    const gate = deps.gate ?? createInFlightGate(limits.maxConcurrent);
+    // 归因落账统一出口：sink 自身异常不吞业务结果也不中断——归因属观测面
+    const record = (entry) => {
+        try {
+            sink(entry);
+        }
+        catch {
+            /* 归因 sink 异常静默——观测面不绑架数据面 */
+        }
+    };
+    return {
+        async fetch(rawUrl, init = {}) {
+            const consumer = init.consumer ?? 'service';
+            const method = init.method ?? 'GET';
+            const startedAt = now();
+            // 进度快照——ok 结局在 task 内记全量；失败结局在外层 catch 记（记到哪
+            // 步算哪步：finalUrl/status 到达即带，早拒即缺席）
+            let finalUrl;
+            let status;
+            let bytes = 0;
+            let redirects = 0;
+            try {
+                return await gate.run(async () => {
+                    // 卫生件 1/5：在飞门（满拒 WEB_RATE_LIMITED——由 gate.run 抛出，外层
+                    // catch 统一落账）
+                    // 卫生件 2/5：URL 解析 + 协议白名单
+                    let url = parseWebUrl(rawUrl);
+                    // 卫生件 3/5：私网判定（字面 + DNS）
+                    await assertPublicHost(url, resolveDns);
+                    // 卫生件 4/5：重定向逐跳跟随（手动——每跳目标重跑三查，跳数触帽拒）
+                    let requestMethod = method;
+                    let requestBody = init.body;
+                    let response;
+                    while (true) {
+                        response = await fetchImpl(url.toString(), {
+                            method: requestMethod,
+                            ...(init.headers ? { headers: init.headers } : {}),
+                            ...(requestBody !== undefined ? { body: requestBody } : {}),
+                            redirect: 'manual',
+                            ...(init.signal ? { signal: init.signal } : {}),
+                        });
+                        if (!REDIRECT_STATUSES.has(response.status))
+                            break;
+                        const location = response.headers.get('location');
+                        if (!location)
+                            break; // 3xx 无 Location——按终态返回（宽容不发明跳转）
+                        if (redirects >= limits.maxRedirects) {
+                            throw new BaseError('WEB_REDIRECT_LIMIT', `重定向跟随触帽（${limits.maxRedirects} 跳）：${rawUrl} → … → ${url.toString()}`);
+                        }
+                        // 跳目标经同一卫生单源复检（协议/私网/DNS——重定向是 SSRF 主载体）
+                        const next = parseWebUrl(new URL(location, url.toString()).toString());
+                        await assertPublicHost(next, resolveDns);
+                        redirects += 1;
+                        url = next;
+                        // 方法改写语义：303 恒转 GET 弃体；301/302 携 POST 按浏览器兼容转
+                        // GET（RFC 保留方法但现实生态如此）；307/308 保方法保体
+                        if (response.status === 303 ||
+                            ((response.status === 301 || response.status === 302) && requestMethod === 'POST')) {
+                            requestMethod = 'GET';
+                            requestBody = undefined;
+                        }
+                    }
+                    // 卫生件 5/5：字节上限（截断非拒）——bytes 先快照（解码失败也记
+                    // 已读字节数），UTF-8 严格解码在后
+                    const read = await readBodyCapped(response, limits.maxBytes);
+                    bytes = read.bytes;
+                    const body = decodeUtf8Strict(read.raw, read.truncated);
+                    finalUrl = url.toString();
+                    status = response.status;
+                    record({
+                        consumer,
+                        method: requestMethod,
+                        url: rawUrl,
+                        finalUrl,
+                        status,
+                        bytes,
+                        redirects,
+                        outcome: 'ok',
+                        at: startedAt,
+                    });
+                    return {
+                        url: rawUrl,
+                        finalUrl,
+                        status,
+                        contentType: response.headers.get('content-type') ?? '',
+                        body,
+                        truncated: read.truncated,
+                        bytes,
+                        redirects,
+                    };
+                });
+            }
+            catch (error) {
+                // 失败结局统一落账：BaseError = 卫生拦截（blocked + 码）；其余 = 普通失败
+                // （DNS/网络/中止/解码——error 档无码）。在飞门拒也经此路（gate.run 内
+                // 先抛，快照全空即早拒形）
+                record({
+                    consumer,
+                    method,
+                    url: rawUrl,
+                    ...(finalUrl !== undefined ? { finalUrl } : {}),
+                    ...(status !== undefined ? { status } : {}),
+                    bytes,
+                    redirects,
+                    outcome: error instanceof BaseError ? 'blocked' : 'error',
+                    ...(error instanceof BaseError ? { errorCode: error.code } : {}),
+                    at: startedAt,
+                });
+                throw error;
+            }
+        },
+    };
+}

package/dist/web/ssrf-guard.js

@@ -0,0 +1,44 @@
+/**
+ * SSRF 守卫 fetch 包裹件（web 卫生单源的第三消费位——03 §10.9 oauth 案
+ * 「SSRF 守卫」挂账收口件，2026-09-09）。
+ *
+ * 承载：oauth 外联腿（credentials 域——人面发起腿与刷新链腿）的 fetch
+ * 预检包裹。插件声明的 deviceAuthUrl/tokenUrl 是任意 URL——宿主外联前
+ * 经 web 卫生单源复用两查（协议白名单 + 私网/保留段拒，字面 + DNS）。
+ *
+ * 定形要点（03 §10.9 定形注同源）：
+ * - **拦截码复用 `WEB_` 族不自造**（browser 件章同律——守卫错即 BaseError
+ *   直传，消费面按码分流）；
+ * - **`redirect: 'manual'` 钉死不跟随**——oauth 端点恒直答 200 形态，3xx
+ *   应答按非 200 由 oauth 层折 FLOW_FAILED 兜底 fail-closed；自动跟随是
+ *   SSRF 首跳绕过主载体（公网 URL 302 → 内网地址），钉死即闭合。重定向
+ *   逐跳跟随编舞只在 web service 唯一实现（service.ts），本件不复制第二份；
+ * - **守卫件住 web 域**——credentials 无 web 边（「本件无 web 边，fetchFn
+ *   宿主装配位注入」），装配位（host 已有 web 边）包裹注入，credentials
+ *   模块零改动。
+ *
+ * 与 web service 的分职：service = 模型可控任意 URL 的全卫生编排（在飞门/
+ * 逐跳重定向/字节帽/归因落账）；本件 = 宿主外联固定端点的窄面包裹（无门
+ * 无帽无归因——端点是插件声明非模型生成，额度面不适用）。
+ */
+import { assertPublicHost, defaultDnsResolver, parseWebUrl } from './hygiene.js';
+/**
+ * 构造 SSRF 守卫 fetch：每次调用先卫生两查（解析 + 协议白名单 → 字面 +
+ * DNS 私网拒），过了才透传底层 fetchImpl（init 原样 + redirect 钉 manual）。
+ *
+ * 返回形 = FetchLike（结构兼容全局 fetch 窄面；credentials OAuthFetchLike
+ * 只消费 ok/status/text 三面——Response 超集，装配位直传即合法注入）。
+ *
+ * @param fetchImpl 底层 fetch（生产 = globalThis.fetch；测试注入桩）
+ * @param resolveDns DNS 解析器（缺省 node:dns/promises lookup all——测试注入）
+ */
+export function createSsrfGuardedFetch(fetchImpl, resolveDns = defaultDnsResolver) {
+    return async (url, init) => {
+        // 卫生两查（卫生单源复用——解析/协议白名单在 parseWebUrl，字面 + DNS
+        // 私网拒在 assertPublicHost；拒即抛 WEB_ 族 BaseError 不透传底层）
+        const parsed = parseWebUrl(url);
+        await assertPublicHost(parsed, resolveDns);
+        // 透传（redirect 钉 manual 不跟随——3xx 按非 200 由消费面折兜底码）
+        return fetchImpl(url, { ...init, redirect: 'manual' });
+    };
+}

package/dist/web/tool.js

@@ -0,0 +1,76 @@
+/**
+ * fetch 工具件（消费面一——模型消费；02 §4.1 席 18「fetch 工具」）。
+ *
+ * 工具面 = WebFetchService 的薄包装：参数 schema 收紧（方法词表/头表/体）
+ * + 卫生拦截码转 isError 数据面（一切失败编码为结果——03 §2.3 工具契约）
+ * + 应答拼模型可见文本（元信息头 + 正文——承 berry fetch 头形思路：URL/
+ *   Content-Type/跳转/截断记全披露，正文分隔线下置）。effect 'read'：GET/
+ *   POST 皆模型读世界动作，不触发审批对与可写根（写盘另有 fs 族——fetch
+ *   不落盘）。
+ *
+ * consumer 标注 'tool'——归因落账与 ctx.fetch 服务消费（'service'）、browser
+ * 导航（'navigate'）三面可区分（同一 execute 路径）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { Type } from 'typebox';
+/** 工具面方法词表（服务面不收紧——插件经 ctx.fetch 可用任意标准方法） */
+const TOOL_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'];
+/**
+ * fetch 工具定义工厂（装载批由装配根经插件注册面挂入工具注册表）。
+ * @param service 三消费面共用的 execute 载体（与 ctx.fetch 服务同一实例）
+ */
+export function createFetchTool(service) {
+    return {
+        name: 'fetch',
+        description: '发起 HTTP(S) 请求取回文本响应（GET 缺省；可 POST/PUT/PATCH/DELETE/HEAD）。' +
+            '自动跟随重定向（上限 5 跳）；响应体上限 1 MiB、超限截断并在回执标注；' +
+            '仅接受 UTF-8 文本（二进制/非 UTF-8 拒）。内网地址（私网/环回段）被' +
+            '安全卫生件拒绝。回执含最终 URL、状态码、Content-Type 与字节数。',
+        parameters: Type.Object({
+            url: Type.String({ description: '完整 URL（须含 http:// 或 https:// 协议）' }),
+            method: Type.Optional(Type.Union(TOOL_METHODS.map((m) => Type.Literal(m)))),
+            headers: Type.Optional(Type.Record(Type.String(), Type.String(), { description: '请求头（可选）' })),
+            body: Type.Optional(Type.String({ description: '请求体（POST/PUT/PATCH 用；字符串形）' })),
+        }, { additionalProperties: false }),
+        effect: 'read',
+        execute: async (args, toolCtx) => {
+            // 管道已按 schema 校验；此处窄化取参（缺省腿全在场判定）
+            const url = String(args.url);
+            const method = typeof args.method === 'string' ? args.method : 'GET';
+            const headers = args.headers && typeof args.headers === 'object' && !Array.isArray(args.headers)
+                ? Object.fromEntries(Object.entries(args.headers).filter((entry) => typeof entry[1] === 'string'))
+                : undefined;
+            const body = typeof args.body === 'string' ? args.body : undefined;
+            try {
+                const response = await service.fetch(url, {
+                    method,
+                    ...(headers ? { headers } : {}),
+                    ...(body !== undefined ? { body } : {}),
+                    ...(toolCtx.signal ? { signal: toolCtx.signal } : {}),
+                    consumer: 'tool',
+                });
+                // 元信息头 + 分隔线 + 正文（截断记显式披露——模型自知内容不完整）
+                const meta = [
+                    `URL: ${response.finalUrl}`,
+                    `Status: ${response.status}`,
+                    `Content-Type: ${response.contentType || '未知'}`,
+                    `Bytes: ${response.bytes}${response.truncated ? `（超上限截断——原文更长）` : ''}`,
+                    ...(response.redirects > 0 ? [`Redirects: ${response.redirects} 跳（入口 ${response.url}）`] : []),
+                ];
+                return {
+                    content: [{ type: 'text', text: `${meta.join('\n')}\n\n---\n\n${response.body}` }],
+                };
+            }
+            catch (error) {
+                // 一切失败编码为 isError 数据面（03 §2.3）——BaseError 携码前置披露
+                // （判别收紧：Node 系统错误也带 code 属性，只认注册码体系成员）
+                const code = error instanceof BaseError ? error.code : undefined;
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: code ? `[${code}] ${message}` : message }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/dist/web/types.js

@@ -0,0 +1,10 @@
+/**
+ * web 件公开类型（02 §4.1 席 18：ctx.fetch + fetch 工具 + SSRF 五卫生件——
+ * 两消费面同一 execute）。
+ *
+ * 件身份：core: 官方插件 15 之 #6（07 §1.1 core:web 行）——fetch 工具（模型
+ * 消费面）/ ctx.fetch 服务（插件消费面）/ browser 导航（第三消费位，03 §10.3
+ * 安全卫生条）三面共用同一 execute 路径与同一在飞门实例。装载态集成（apply
+ * 注册工具 + provide 服务）归批 12 后装载面；本批纯逻辑腿。
+ */
+export {};