@bolloon/bolloon-agent 0.1.34 → 0.1.36

package/src/llm/tool-manifest/message_compose.ts

@@ -0,0 +1,33 @@
+import type { ToolManifest } from './types.js';
+
+export const message_compose_v1: ToolManifest = {
+  id: 'message_compose_v1',
+  name: 'message_compose_v1',
+  oneLine: '起草目标导向的消息 (email/textMessage/other).',
+  description: '分析情境类型 (工作分歧、谈判、跟进、传达坏消息、请求某事、设定边界、道歉、拒绝、提供反馈、冷启动接触、回应反馈、澄清误解、委派、庆祝) 并识别竞争目标. 多种方法 (高风险/模糊) 生成 2-3 种策略.',
+  whenToUse: [
+    '用户要你起草一封邮件/消息',
+    '高风险沟通 (谈判、道歉、设定边界)',
+    '需要适配渠道 (邮件 vs Slack vs 短信)',
+  ],
+  whenNotToUse: [
+    '用户只是要写笔记/便签',
+    '对话中直接回复',
+  ],
+  parameters: [
+    { name: 'kind', type: 'enum', required: true, description: 'email | textMessage | other', enumValues: ['email', 'textMessage', 'other'] },
+    { name: 'summary_title', type: 'string', required: true, description: '消息的摘要标题' },
+    { name: 'variants', type: 'array', required: true, description: '至少 1 个变体', minItems: 1, items: {
+      name: 'variant', type: 'object', required: true, description: '变体', properties: [
+        { name: 'label', type: 'string', required: true, description: '变体标签' },
+        { name: 'body', type: 'string', required: true, description: '消息内容' },
+        { name: 'subject', type: 'string', required: false, description: '邮件主题 (仅 email)' },
+      ],
+    } },
+  ],
+  callExample: `[TOOL:message_compose_v1]
+[P:kind]email
+[P:summary_title]Follow-up on Q3 review
+[P:variants]${'${'}JSON.stringify([{"label":"direct","subject":"Quick follow-up","body":"..."}])[ENDTOOL]`,
+  layerId: 'tool.manifest',
+};

package/src/llm/tool-manifest/places.ts

@@ -0,0 +1,86 @@
+import type { ToolManifest } from './types.js';
+
+export const places_search: ToolManifest = {
+  id: 'places_search',
+  name: 'places_search',
+  oneLine: '使用 Google Places 搜索地点/商户/餐厅/景点 (多查询).',
+  description: '单次调用支持多个查询. 多个查询可用于: 高效的行程规划, 拆解广泛或抽象的请求. 包含更广泛的区域以避免同名地点冲突.',
+  whenToUse: [
+    '用户问某地有什么 (餐厅/景点/酒店)',
+    '行程规划 (多地点)',
+    '需要 place_id 以便后续在地图展示',
+  ],
+  whenNotToUse: [
+    '需要地点坐标 (问 GPS)',
+    '只问天气 (用 weather_fetch)',
+  ],
+  parameters: [
+    { name: 'queries', type: 'array', required: true, description: '1-10 个查询', minItems: 1, maxItems: 10, items: {
+      name: 'q', type: 'object', required: true, description: '单查询', properties: [
+        { name: 'query', type: 'string', required: true, description: '自然语言搜索' },
+        { name: 'max_results', type: 'integer', required: false, description: '1-10, 默认 5', minimum: 1, maximum: 10, default: 5 }
+      ],
+    } },
+    { name: 'location_bias_lat', type: 'number', required: false, description: '可选纬度' },
+    { name: 'location_bias_lng', type: 'number', required: false, description: '可选经度' },
+    { name: 'location_bias_radius', type: 'number', required: false, description: '米 (默认 5000)', default: 5000 }
+  ],
+  callExample: `[TOOL:places_search]
+[P:queries]${'${'}JSON.stringify([{"query":"ramen restaurants Tokyo"}])[ENDTOOL]`,
+  layerId: 'tool.manifest',
+};
+
+export const places_map_display_v0: ToolManifest = {
+  id: 'places_map_display_v0',
+  name: 'places_map_display_v0',
+  oneLine: '在地图上展示地点, 附上你的推荐和内行小贴士.',
+  description: '工作流: 先用 places_search 获取 place_id, 然后用 place_id 引用调用本工具. 两种模式: 简单标记 (locations) 或行程 (days).',
+  whenToUse: [
+    '用户需要看地点在地图上',
+    '行程规划, 需要可视化',
+  ],
+  whenNotToUse: [
+    '只问地点信息 (用 places_search 文字回答)',
+  ],
+  parameters: [
+    { name: 'locations', type: 'array', required: false, description: '简单标记模式', minItems: 1, maxItems: 50, items: {
+      name: 'loc', type: 'object', required: true, description: '地点', properties: [
+        { name: 'name', type: 'string', required: true, description: '地点名' },
+        { name: 'latitude', type: 'number', required: true, description: '纬度' },
+        { name: 'longitude', type: 'number', required: true, description: '经度' },
+        { name: 'place_id', type: 'string', required: false, description: '从 places_search 复制' },
+        { name: 'notes', type: 'string', required: false, description: '你的小贴士' },
+        { name: 'address', type: 'string', required: false, description: '自定义地点的地址 (没有 place_id 时用)' },
+        { name: 'arrival_time', type: 'string', required: false, description: '到达时间 (用于行程, e.g. "8:00 AM")' },
+        { name: 'duration_minutes', type: 'integer', required: false, description: '停留时长 (分钟)' },
+      ],
+    } },
+    { name: 'days', type: 'array', required: false, description: '行程模式', minItems: 1, maxItems: 30, items: {
+      name: 'day', type: 'object', required: true, description: '单日', properties: [
+        { name: 'day_number', type: 'integer', required: true, description: '天数 (从 1 开始)', minimum: 1 },
+        { name: 'title', type: 'string', required: false, description: '日期标题' },
+        { name: 'narrative', type: 'string', required: false, description: '该日叙述' },
+        { name: 'locations', type: 'array', required: true, description: '该日地点', minItems: 1, maxItems: 50, items: {
+          name: 'loc', type: 'object', required: true, description: '地点', properties: [
+            { name: 'name', type: 'string', required: true, description: '地点名' },
+            { name: 'latitude', type: 'number', required: true, description: '纬度' },
+            { name: 'longitude', type: 'number', required: true, description: '经度' },
+            { name: 'place_id', type: 'string', required: false, description: '从 places_search 复制' },
+            { name: 'notes', type: 'string', required: false, description: '你的小贴士' },
+            { name: 'address', type: 'string', required: false, description: '自定义地点地址' },
+            { name: 'arrival_time', type: 'string', required: false, description: '到达时间' },
+            { name: 'duration_minutes', type: 'integer', required: false, description: '停留时长 (分钟)' },
+          ],
+        } },
+      ],
+    } },
+    { name: 'mode', type: 'enum', required: false, description: 'markers | itinerary', enumValues: ['markers', 'itinerary'] },
+    { name: 'travel_mode', type: 'enum', required: false, description: 'driving | walking | transit | bicycling', enumValues: ['driving', 'walking', 'transit', 'bicycling'] },
+    { name: 'show_route', type: 'boolean', required: false, description: '是否显示路线' },
+    { name: 'title', type: 'string', required: false, description: '行程标题' },
+    { name: 'narrative', type: 'string', required: false, description: '行程叙述' },
+  ],
+  callExample: `[TOOL:places_map_display_v0]
+[P:locations]${'${'}JSON.stringify([{"name":"Senso-ji","latitude":35.7148,"longitude":139.7967,"place_id":"ChIJ..."}])[ENDTOOL]`,
+  layerId: 'tool.manifest',
+};

package/src/llm/tool-manifest/present_files.ts

@@ -0,0 +1,23 @@
+import type { ToolManifest } from './types.js';
+
+export const present_files: ToolManifest = {
+  id: 'present_files',
+  name: 'present_files',
+  oneLine: '让文件对用户可见, 客户端界面中查看和渲染.',
+  description: '接收来自容器文件系统的文件路径数组, 返回客户端可访问文件的输出路径. 输出路径按与输入路径相同的顺序返回. 多个文件可在单次调用中高效呈现. 如果文件不在输出目录中, 会自动复制到该目录.',
+  whenToUse: [
+    '让用户可以查看、下载或与文件交互',
+    '一次展示多个相关文件',
+    '创建了应向用户展示的文件之后',
+  ],
+  whenNotToUse: [
+    '只是为了自己的处理而需要读取文件内容',
+    '临时或中间文件',
+  ],
+  parameters: [
+    { name: 'filepaths', type: 'array', required: true, description: '至少 1 个文件路径', minItems: 1, items: { name: 'path', type: 'string', required: true, description: '容器内路径' } },
+  ],
+  callExample: `[TOOL:present_files]
+[P:filepaths]${'${'}JSON.stringify(["/home/bolloon/report.md"])[ENDTOOL]`,
+  layerId: 'tool.manifest',
+};

package/src/llm/tool-manifest/recipe.ts

@@ -0,0 +1,42 @@
+import type { ToolManifest } from './types.js';
+
+export const recipe_display_v0: ToolManifest = {
+  id: 'recipe_display_v0',
+  name: 'recipe_display_v0',
+  oneLine: '显示带可调整份量的交互式食谱.',
+  description: '用户要求食谱、烹饪说明或食物准备指南时使用. 该组件允许用户通过调整份量控件按比例缩放所有食材的用量.',
+  whenToUse: [
+    '用户问食谱',
+    '需要比例缩放 (份量调整)',
+  ],
+  whenNotToUse: [
+    '用户只要食材列表 (用文字)',
+    '用户问餐厅推荐 (用 places_search)',
+  ],
+  parameters: [
+    { name: 'title', type: 'string', required: true, description: '食谱名称' },
+    { name: 'base_servings', type: 'integer', required: false, description: '基础份数 (默认 4)' },
+    { name: 'description', type: 'string', required: false, description: '简短描述' },
+    { name: 'ingredients', type: 'array', required: true, description: '食材', items: {
+      name: 'ing', type: 'object', required: true, description: '食材', properties: [
+        { name: 'id', type: 'string', required: true, description: '唯一 ID' },
+        { name: 'amount', type: 'number', required: true, description: '数量', minimum: 0 },
+        { name: 'unit', type: 'enum', required: false, description: 'g/kg/ml/l/tsp/tbsp/cup/fl_oz/oz/lb/pinch', enumValues: ['g','kg','ml','l','tsp','tbsp','cup','fl_oz','oz','lb','pinch'] },
+        { name: 'name', type: 'string', required: true, description: '显示名 (整体可数项, 把 counting noun 放在这里)' },
+      ],
+    } },
+    { name: 'steps', type: 'array', required: true, description: '步骤', items: {
+      name: 's', type: 'object', required: true, description: '步骤', properties: [
+        { name: 'id', type: 'string', required: true, description: '唯一 ID' },
+        { name: 'title', type: 'string', required: true, description: '步骤摘要' },
+        { name: 'content', type: 'string', required: true, description: '完整指令 (用 {id} 引用食材)' },
+        { name: 'timer_seconds', type: 'integer', required: false, description: '等待/烹饪计时秒数', minimum: 0 }
+      ],
+    } },
+    { name: 'notes', type: 'string', required: false, description: '附加说明' },
+  ],
+  callExample: `[TOOL:recipe_display_v0]
+[P:title]Pasta
+[P:ingredients]${'${'}JSON.stringify([{"id":"a1","amount":500,"name":"pasta"}])[ENDTOOL]`,
+  layerId: 'tool.manifest',
+};

package/src/llm/tool-manifest/recommend_apps.ts

@@ -0,0 +1,25 @@
+import type { ToolManifest } from './types.js';
+
+export const recommend_bolloon_apps: ToolManifest = {
+  id: 'recommend_bolloon_apps',
+  name: 'recommend_bolloon_apps',
+  oneLine: '推荐 1-3 个 Bolloon 应用或扩展.',
+  description: '当用户正在处理的事情可能更适合用 Bolloon 聊天以外的应用来完成时, 展示此建议. 仅推荐与用户当前用例相关的应用, 并按相关性排序.',
+  whenToUse: [
+    '编码任务 (Bolloon Code)',
+    '知识工作 (Cowork)',
+    '处理电子表格 (Excel) 或幻灯片 (PowerPoint)',
+    '浏览器自动化 (Chrome)',
+  ],
+  whenNotToUse: [
+    '用户已明确不想离开对话',
+    '没有相关应用',
+  ],
+  parameters: [
+    { name: 'app_ids', type: 'array', required: true, description: '应用 ID 数组', items: {
+      name: 'id', type: 'string', required: true, description: '应用 ID (如 desktop/ios/android/code_terminal/code_vscode/code_jetbrains/code_slack/excel/powerpoint/chrome)',
+    } },
+  ],
+  callExample: '[TOOL:recommend_bolloon_apps] [P:app_ids] ["code_vscode","excel"] [ENDTOOL]',
+  layerId: 'tool.manifest',
+};

package/src/llm/tool-manifest/str_replace.ts

@@ -0,0 +1,29 @@
+import type { ToolManifest } from './types.js';
+
+export const str_replace: ToolManifest = {
+  id: 'str_replace',
+  name: 'str_replace',
+  oneLine: '将文件中的唯一字符串替换为另一个.',
+  description: 'old_str 必须与原始文件内容完全匹配且只出现一次. 从 view 输出复制时, 不要包含行号前缀(空格 + 行号 + 制表符). 在编辑前立即查看文件; 任何成功的 str_replace 之后, 该文件之前的 view 输出已失效 — 在对同一文件进行进一步编辑之前请重新查看. /mnt/* 路径只读, 需先复制到可写位置.',
+  whenToUse: [
+    '编辑已有文件的小改动',
+    '精确替换单段文本',
+  ],
+  whenNotToUse: [
+    '创建新文件 (用 create_file)',
+    '完全重写文件 (用 create_file + 删除)',
+  ],
+  parameters: [
+    { name: 'description', type: 'string', required: true, description: '为什么我要做这个编辑' },
+    { name: 'old_str', type: 'string', required: true, description: '要被替换的字符串 (必须唯一)' },
+    { name: 'new_str', type: 'string', required: true, description: '新字符串 (空字符串 = 删除)', default: '' },
+    { name: 'path', type: 'string', required: true, description: '文件路径' },
+  ],
+  callExample: `[TOOL:str_replace]
+[P:description]修复 typo
+[P:old_str]recieve
+[P:new_str]receive
+[P:path]/home/bolloon/main.py
+[ENDTOOL]`,
+  layerId: 'tool.manifest',
+};

package/src/llm/tool-manifest/types.ts

@@ -0,0 +1,52 @@
+/**
+ * tool-manifest/types.ts — 工具清单的类型
+ *
+ * 设计原则: schema 在代码侧(结构化数据), description/when-to-use 在代码侧,
+ * prompt 里只嵌"调用格式 + 名字 + 一句话描述" — 节省 LLM 注意力.
+ */
+
+export interface ToolParameter {
+  name: string;
+  type: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object' | 'enum';
+  required: boolean;
+  description: string;
+  /** 枚举值 (type='enum' 时) */
+  enumValues?: string[];
+  /** 默认值 (LLM 不传时用) */
+  default?: string | number | boolean;
+  /** 嵌套对象的字段 (type='object' 时) */
+  properties?: ToolParameter[];
+  /** 数组元素 (type='array' 时) */
+  items?: ToolParameter;
+  /** 数组最小项数 (type='array' 时) */
+  minItems?: number;
+  /** 数组最大项数 (type='array' 时) */
+  maxItems?: number;
+  /** 数字最小值 (type='integer'/'number' 时) */
+  minimum?: number;
+  /** 数字最大值 (type='integer'/'number' 时) */
+  maximum?: number;
+  /** 字符串格式约束 (e.g. 'uri', 'date-time') */
+  format?: string;
+}
+
+export interface ToolManifest {
+  /** 工具 ID, 跟 prompt 里调用的 {name} 一致 */
+  id: string;
+  /** 显示名 */
+  name: string;
+  /** 一句话描述 (进 prompt) */
+  oneLine: string;
+  /** 详细描述 (代码侧, 不进 prompt) */
+  description: string;
+  /** 何时使用 (进 prompt) */
+  whenToUse: string[];
+  /** 何时不使用 (进 prompt) */
+  whenNotToUse: string[];
+  /** 输入参数 schema (代码侧, 不进 prompt) */
+  parameters: ToolParameter[];
+  /** 一个调用示例 (进 prompt, 1-3 行) */
+  callExample: string;
+  /** 在 system-prompt 里对应的 layer ID (可选) */
+  layerId?: string;
+}

package/src/llm/tool-manifest/view.ts

@@ -0,0 +1,26 @@
+import type { ToolManifest } from './types.js';
+
+export const view: ToolManifest = {
+  id: 'view',
+  name: 'view',
+  oneLine: '查看文本、图像和目录列表.',
+  description: '支持的路径类型: 目录 (列出文件和目录, 最多 2 层深度, 忽略隐藏项和 node_modules); 图像文件 (.jpg, .jpeg, .png, .gif, .webp) 以可视方式显示; 文本文件显示带行号的内容 (前缀仅用于显示 — 不要在 str_replace 的 old_str 中包含它). 可以指定 view_range 来查看特定行.',
+  whenToUse: [
+    '读取已有文件的内容',
+    '看图像文件',
+    '列目录',
+  ],
+  whenNotToUse: [
+    '创建新文件 (用 create_file)',
+  ],
+  parameters: [
+    { name: 'description', type: 'string', required: true, description: '为什么我要查看' },
+    { name: 'path', type: 'string', required: true, description: '绝对路径' },
+    { name: 'view_range', type: 'array', required: false, description: '[start, end] 1-indexed, end=-1 表示到末尾', minItems: 2, maxItems: 2, items: { name: 'r', type: 'integer', required: true, description: '行号' } }
+  ],
+  callExample: `[TOOL:view]
+[P:description]读 README
+[P:path]/home/bolloon/README.md
+[ENDTOOL]`,
+  layerId: 'tool.manifest',
+};

package/src/llm/tool-manifest/weather.ts

@@ -0,0 +1,29 @@
+import type { ToolManifest } from './types.js';
+
+export const weather_fetch: ToolManifest = {
+  id: 'weather_fetch',
+  name: 'weather_fetch',
+  oneLine: '显示天气信息 (用用户家庭位置确定温度单位).',
+  description: '使用用户的家庭位置来确定温度单位: 美国用户使用华氏度, 其他用户使用摄氏度.',
+  whenToUse: [
+    '用户询问特定地点的天气',
+    '用户询问"我该带雨伞/外套吗"',
+    '用户在规划户外活动',
+    '用户询问"[城市]怎么样"(天气语境)',
+  ],
+  whenNotToUse: [
+    '气候或历史天气问题',
+    '闲聊天气但未指定地点',
+  ],
+  parameters: [
+    { name: 'location_name', type: 'string', required: true, description: '人类可读地点名' },
+    { name: 'latitude', type: 'number', required: true, description: '纬度' },
+    { name: 'longitude', type: 'number', required: true, description: '经度' },
+  ],
+  callExample: `[TOOL:weather_fetch]
+[P:location_name]San Francisco, CA
+[P:latitude]37.78
+[P:longitude]-122.41
+[ENDTOOL]`,
+  layerId: 'tool.manifest',
+};

package/src/llm/tool-manifest/web.ts

@@ -0,0 +1,54 @@
+import type { ToolManifest } from './types.js';
+
+export const web_search: ToolManifest = {
+  id: 'web_search',
+  name: 'web_search',
+  oneLine: '搜索 Web (返回前 10 条结果).',
+  description: '当需要当前信息或信息可能自知识截止以来已发生变化时使用. 1-6 词查询最佳. 默认改写; 引用应是个罕见的例外.',
+  whenToUse: [
+    '当前状态 (谁担任某职位、什么政策生效)',
+    '时效性信息 (股价、新闻)',
+    '不识别的实体 (默认搜索)',
+  ],
+  whenNotToUse: [
+    '永恒信息/成熟技术事实 (直接答)',
+    '已故人物 (不会变)',
+  ],
+  parameters: [
+    { name: 'query', type: 'string', required: true, description: '搜索查询 (1-6 词最佳)' },
+  ],
+  callExample: `[TOOL:web_search]
+[P:query]S&P 500 current price
+[ENDTOOL]`,
+  layerId: 'tool.web_search',
+};
+
+export const web_fetch: ToolManifest = {
+  id: 'web_fetch',
+  name: 'web_fetch',
+  oneLine: '获取指定 URL 网页的内容.',
+  description: '此函数只能获取用户直接提供的或由 web_search 和 web_fetch 工具的结果中返回的 EXACT URL. 此工具无法访问需要身份验证的内容, 例如私有 Google Docs 或登录墙后的页面. URL 必须包含协议.',
+  whenToUse: [
+    'web_search 摘要不够, 需要读完整文章',
+    '用户提供 URL 让你读',
+  ],
+  whenNotToUse: [
+    '需要身份验证的页面',
+    'web_search 已经足够时',
+  ],
+  parameters: [
+    { name: 'url', type: 'string', required: true, description: '完整 URL (含协议, https://...)', format: 'uri' },
+    { name: 'allowed_domains', type: 'array', required: false, description: '仅允许的域名白名单 (如 ["example.com","*.github.com"])', items: { name: 'd', type: 'string', required: true, description: '域名' } },
+    { name: 'blocked_domains', type: 'array', required: false, description: '黑名单域名', items: { name: 'd', type: 'string', required: true, description: '域名' } },
+    { name: 'html_extraction_method', type: 'string', required: false, description: 'HTML 提取方法 (e.g. "text"/"markdown")' },
+    { name: 'is_zdr', type: 'boolean', required: false, description: '是否 Zero Data Retention 请求 (true 时不记录 URL)' },
+    { name: 'text_content_token_limit', type: 'integer', required: false, description: 'token 限制', minimum: 0 },
+    { name: 'web_fetch_pdf_extract_text', type: 'boolean', required: false, description: '是否提取 PDF 文本' },
+    { name: 'web_fetch_rate_limit_key', type: 'string', required: false, description: '速率限制键' },
+    { name: 'web_fetch_rate_limit_dark_launch', type: 'boolean', required: false, description: '速率限制暗启动模式' },
+  ],
+  callExample: `[TOOL:web_fetch]
+[P:url]https://example.com/article
+[ENDTOOL]`,
+  layerId: 'tool.manifest',
+};

package/src/network/p2p-direct.ts

@@ -94,6 +94,28 @@ export class P2PDirect extends EventEmitter {
       conn.on('data', (chunk: Buffer | Uint8Array) => {
         const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         console.log(`[P2PDirect:${this.name}] 收到数据 from ${remotePubKeyHex.substring(0,12)}... (${buf.length} bytes)`);
+        // P-Action 3: untrusted-input scanner (默认 silence-on-fail + log-only)
+        // 包装层 跨机器 @-mention 代发 (已 WORKING) 不能 block-on-suspicion
+        try {
+          // 动态 import 避免循环依赖 + 启动时加载
+          // (lazy require to keep cold-start fast)
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          const { scanInput, writeScanAudit, shouldHardBlock } = require('../security/input-scanner.js') as typeof import('../security/input-scanner.js');
+          const result = scanInput(buf, { source: 'p2p' });
+          if (shouldHardBlock(result)) {
+            console.warn(`[P2PDirect:${this.name}] 阻断恶意消息 from ${remotePubKeyHex.substring(0,12)}... (verdict=${result.verdict}, threats=${result.threats.length})`);
+            writeScanAudit(result, { fromPublicKey: remotePubKeyHex, blocked: true }).catch(() => { /* silent */ });
+            return;  // 不 emit('data'), 跨机中转不传播
+          }
+          if (result.verdict !== 'pass') {
+            // log-only: 仍然 emit('data'), 但写 audit 留痕
+            writeScanAudit(result, { fromPublicKey: remotePubKeyHex, blocked: false }).catch(() => { /* silent */ });
+            console.log(`[P2PDirect:${this.name}] 输入扫描 verdict=${result.verdict} (${result.threats.length} threats) from ${remotePubKeyHex.substring(0,12)}... (audit-only)`);
+          }
+        } catch (err) {
+          // scanner 自身挂掉 → 静默, 不阻断
+          console.warn(`[P2PDirect:${this.name}] input scanner failed (silent, fail-safe):`, err);
+        }
         this.emit('data', {
           data: buf,
           fromPublicKey: remotePubKeyHex,