@bolloon/bolloon-agent 0.3.1 → 0.3.4

package/dist/judgeness/visibility.js

@@ -0,0 +1,118 @@
+/**
+ * judgeness · visibility.ts
+ *
+ * 三道授权闸的核心实现:
+ *   闸 1: id-visibility scrubber     出站前按 audience 字段过滤
+ *   闸 2: channel-allowlist gate     joinPeer / joinTopic 前的白名单
+ *   闸 3: human-override handler     任何写入由人类 override 优先
+ *
+ * 复用了现有 sanitizeChannelForPeer 模式 (src/web/server-v3-p2p.ts:54) 的思路:
+ *   不引额外依赖; 默认 fail-closed (闸 1/2); 闸 3 fail-人类优先.
+ */
+import { loadVisibility, isPubkeyAllowed } from './store.js';
+/** 三态映射:
+ *  - locked + agent 写入 → 拒
+ *  - locked + human 写入 → 允许
+ *  - open + 任意 → 允许 (但要过闸 2 allowlist)
+ *  - human-only + agent 写入 → 拒
+ *  - visibility.yaml.humanOverride=true → 完全优先于 agent openState
+ */
+export function resolveGate3(desc, ctx, visFile) {
+    // 闸 3 先看 visibility.yaml.humanOverride (强制)
+    const visCard = visFile.cards.find((c) => c.descriptionId === desc.descriptionId);
+    const visChan = ctx.channelTopic
+        ? visFile.channels.find((c) => c.channelId === ctx.channelTopic)
+        : undefined;
+    const humanOverride = visCard?.humanOverride ?? visChan?.humanOverride ?? false;
+    const effectiveOpenState = visCard?.openState ?? visChan?.openState ?? desc.openState;
+    // humanOverride=true 时, agent 永不能写, 即使 openState=open
+    if (humanOverride && ctx.role !== 'human') {
+        return { allow: false, reason: 'humanOverride=true and writer is not human' };
+    }
+    // human-only 状态: 仅 human
+    if (effectiveOpenState === 'human-only' && ctx.role !== 'human') {
+        return { allow: false, reason: 'openState=human-only rejects agent' };
+    }
+    // locked 状态: agent 不能自动 share / publish (但可写入本地 draft)
+    if (effectiveOpenState === 'locked' && ctx.role === 'agent') {
+        return { allow: false, reason: 'openState=locked rejects agent auto-write' };
+    }
+    return { allow: true, reason: 'ok' };
+}
+/** 给 audience 一份 description 的可见版本. */
+export async function scrubForAudience(desc, audience) {
+    const vis = await loadVisibility();
+    const visCard = vis.cards.find((c) => c.descriptionId === desc.descriptionId);
+    const visChan = audience.channelTopic
+        ? vis.channels.find((c) => c.channelId === audience.channelTopic)
+        : undefined;
+    const effectiveVis = visCard?.visibility ?? visChan?.visibility ?? desc.visibility;
+    const base = {
+        descriptionId: desc.descriptionId,
+        judgmentRef: desc.judgmentRef,
+        visibility: effectiveVis,
+        openState: visCard?.openState ?? visChan?.openState ?? desc.openState,
+    };
+    // private 仅 self 可见
+    if (effectiveVis === 'private' && audience.pubkey !== '__self__') {
+        return base;
+    }
+    // peers 仅已 join 的 peer (这里简化为: 任何非 self 都视为 peer-by-default)
+    if (effectiveVis === 'peers' && audience.pubkey === '__self__') {
+        return { ...base, facets: desc.facets, basis: desc.basis, scope: desc.scope, by: desc.by, createdAt: desc.createdAt };
+    }
+    // allowlist
+    if (effectiveVis === 'allowlist') {
+        if (audience.pubkey === '__self__') {
+            return { ...base, facets: desc.facets, basis: desc.basis, scope: desc.scope, by: desc.by, createdAt: desc.createdAt };
+        }
+        const allowed = await isPubkeyAllowed(audience.pubkey);
+        if (!allowed)
+            return base;
+    }
+    // public
+    return {
+        ...base,
+        facets: desc.facets,
+        basis: desc.basis,
+        scope: desc.scope,
+        by: desc.by,
+        createdAt: desc.createdAt,
+    };
+}
+/** 批量. 顺序: scrub → 过滤 private (self-only). */
+export async function scrubListForAudience(descs, audience) {
+    const out = [];
+    for (const d of descs) {
+        const s = await scrubForAudience(d, audience);
+        out.push(s);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// 闸 2 — allowlist gate (joinPeer / joinTopic 前)
+// ---------------------------------------------------------------------------
+/** resolveGate2: true = 允许 join. */
+export async function resolveGate2(audiencePubkey, targetChannel, visFile) {
+    // 自我永远放行
+    if (audiencePubkey === '__self__')
+        return { allow: true, reason: 'self' };
+    const f = visFile ?? (await loadVisibility());
+    const chan = f.channels.find((c) => c.channelId === targetChannel);
+    if (!chan) {
+        // channel 没登记 = 默认 allowlist 模式 (闸 2 fail-closed)
+        const allowed = await isPubkeyAllowed(audiencePubkey);
+        return allowed
+            ? { allow: true, reason: 'default allowlist: pk in list' }
+            : { allow: false, reason: 'default allowlist: pk not in list' };
+    }
+    if (chan.visibility === 'public')
+        return { allow: true, reason: 'channel=public' };
+    if (chan.visibility === 'private')
+        return { allow: false, reason: 'channel=private' };
+    // allowlist / peers 都要求在白名单
+    const allowed = await isPubkeyAllowed(audiencePubkey);
+    return allowed
+        ? { allow: true, reason: 'allowlist match' }
+        : { allow: false, reason: 'allowlist miss' };
+}

package/dist/llm/config-store.js

@@ -65,7 +65,9 @@ export const DEFAULT_PROVIDER_CONFIGS = {
         enabled: false,
         apiKey: '',
         baseUrl: 'https://api.deepseek.com/v1',
-        model: 'deepseek-chat',
+        // 2026-07-17: deepseek-chat (V3) 已不在官方 model list, 迁到 V4 系列 — deepseek-v4-flash
+        //   1M context, 支持 tool calls, 默认 thinking mode (官方 https://api-docs.deepseek.com/quick_start/pricing)
+        model: 'deepseek-v4-flash',
         temperature: 0.7,
         maxTokens: 4096,
         requiresApiKey: true
@@ -134,7 +136,8 @@ export const PROVIDER_INFO = {
         requiresApiKey: true,
         models: ['MiniMax-M3', 'MiniMax-M2.7', 'MiniMax-M2', 'MiniMax-M2.1-highspeed', 'MiniMax-M2.7-highspeed']
     },
-    deepseek: { name: 'DeepSeek', description: '深度求索大模型', requiresApiKey: true, models: ['deepseek-chat', 'deepseek-reasoner'] },
+    // 2026-07-17: V3 系列 (deepseek-chat / deepseek-reasoner) 官方已下线, 改 V4
+    deepseek: { name: 'DeepSeek', description: '深度求索大模型 (V4)', requiresApiKey: true, models: ['deepseek-v4-flash', 'deepseek-v4-pro'] },
     kimi: { name: 'Kimi (月之暗面)', description: 'Moonshot 长上下文模型', requiresApiKey: true, models: ['moonshot-v1-8k', 'moonshot-v1-32k', 'moonshot-v1-128k'] },
     glm: { name: 'GLM (智谱)', description: '智谱 ChatGLM 系列模型', requiresApiKey: true, models: ['glm-4-flash', 'glm-4', 'glm-4-plus', 'glm-4-air', 'glm-4-airx'] },
     qwen: { name: 'Qwen (通义千问)', description: '阿里云通义千问系列', requiresApiKey: true, models: ['qwen-plus', 'qwen-max', 'qwen-turbo', 'qwen-long'] },

package/dist/llm/pi-ai.js

@@ -68,7 +68,7 @@ export class PiAIModel {
      *   LLM 看不到 tool 调用的真实结果,导致 CLI loop 卡死.
      *   现在 messages 数组版本保留 role 语义, LLM 能正确看到工具返回.
      */
-    async chat(messageOrMessages, contextOrSystemPrompt, signal) {
+    async chat(messageOrMessages, contextOrSystemPrompt, signal, tools) {
         const systemPrompt = await this.buildSystemPromptAsync(contextOrSystemPrompt);
         let messages;
         if (Array.isArray(messageOrMessages)) {
@@ -93,6 +93,7 @@ export class PiAIModel {
                 temperature: 0.8,
                 maxTokens: 16384, // 2026-06-17: 提到 16384 — agent 注入 16K+ system prompt + 8K tool defs 时, 8K 撞上限返回空 content (见 memory: bolloon-llm-empty-large-prompt)
                 signal,
+                tools, // pass through for native tool calling
             });
             return { reply: response.reply, toolCalls: response.toolCalls };
         }
@@ -166,9 +167,10 @@ export class PiAIModel {
                 console.warn('[pi-ai] systemPrepend 失败:', err?.message?.slice(0, 100));
             }
         }
+        let openaiTools;
         if (tools && tools.length > 0) {
             try {
-                const { getToolManifest, formatForPrompt } = await import('./tool-manifest/index.js');
+                const { getToolManifest, formatForPrompt, formatForOpenAI } = await import('./tool-manifest/index.js');
                 const manifests = tools
                     .map((id) => getToolManifest(id))
                     .filter((m) => m !== undefined);
@@ -178,6 +180,8 @@ export class PiAIModel {
                         { role: 'system', content: toolPrompt },
                         ...messages,
                     ];
+                    // Bug 3: 从 manifests 生成原生 OpenAI tools 格式
+                    openaiTools = formatForOpenAI(manifests);
                 }
             }
             catch (err) {
@@ -192,7 +196,7 @@ export class PiAIModel {
             case 'glm':
             case 'qwen':
             case 'mimo':
-                return this.callOpenAI(finalMessages, temperature, maxTokens, signal);
+                return this.callOpenAI(finalMessages, temperature, maxTokens, signal, openaiTools);
             case 'anthropic':
                 return this.callAnthropic(finalMessages, temperature, maxTokens, signal);
             case 'ollama':
@@ -259,7 +263,8 @@ export class PiAIModel {
             // The 3.x line ships as `-flash` only — there is no `gemini-3.x-pro`.
             gemini: this.config.model || 'gemini-2.5-pro',
             minimax: this.config.model || process.env.MINIMAX_MODEL || 'MiniMax-M3',
-            deepseek: this.config.model || process.env.DEEPSEEK_MODEL || 'deepseek-chat',
+            // 2026-07-17: deepseek-chat (V3) 官方已下线, 迁 deepseek-v4-flash
+            deepseek: this.config.model || process.env.DEEPSEEK_MODEL || 'deepseek-v4-flash',
             kimi: this.config.model || process.env.KIMI_MODEL || process.env.MOONSHOT_MODEL || 'moonshot-v1-8k',
             glm: this.config.model || process.env.GLM_MODEL || process.env.ZHIPU_MODEL || 'glm-4-flash',
             qwen: this.config.model || process.env.QWEN_MODEL || process.env.DASHSCOPE_MODEL || 'qwen-plus',
@@ -269,7 +274,7 @@ export class PiAIModel {
         };
         return modelMap[this.provider];
     }
-    async callOpenAI(messages, temperature, maxTokens, signal) {
+    async callOpenAI(messages, temperature, maxTokens, signal, tools) {
         const apiKey = this.getApiKey();
         if (!apiKey) {
             throw new Error('OPENAI_API_KEY not set');
@@ -280,14 +285,12 @@ export class PiAIModel {
             temperature,
             max_tokens: maxTokens
         };
-        // 2026-06-19: 一次命中优化 — 收到空 content 时重试 2 次, 避免 minimax 上游网络抖动
-        //   经验: minimax 偶发返回 200 但 content="" (上游 retry 耗尽), 之前当作 sentinel
-        //   现在外层加 2 次重试 + 退避, 让 90%+ 的一次调用不出现错误
-        // 2026-06-19: 一次命中优化 — 收到空 content 时重试 2 次, 避免 minimax 上游网络抖动
-        //   经验: minimax 偶发返回 200 但 content="" (上游 retry 耗尽), 之前当作 sentinel
-        //   现在外层加 2 次重试 + 退避, 让 90%+ 的一次调用不出现错误
+        // Bug 3: 传入原生 tools 参数 + tool_choice auto, LLM 返回结构化 tool_calls
+        if (tools && tools.length > 0) {
+            requestBody.tools = tools;
+            requestBody.tool_choice = 'auto';
+        }
         let lastFinishReason = '';
-        // 2026-07-06: 加分阶段 instrumentation — 让"9.8s 大头是哪段"可定位
         const _t0 = Date.now();
         for (let attempt = 0; attempt < 3; attempt++) {
             const _tFetch = Date.now();
@@ -313,24 +316,23 @@ export class PiAIModel {
             const content = choice?.message?.content || '';
             const toolCalls = choice?.message?.tool_calls;
             lastFinishReason = choice?.finish_reason || '';
-            if (content) {
+            // Bug 7: tool_calls 存在时不走重试 — LLM 选工具时 content 空是合法的
+            if (content || (toolCalls && toolCalls.length > 0)) {
                 if (lastFinishReason === 'length') {
                     console.warn(`[pi-ai] hit max_tokens ceiling (model=${this.mapModel()}, max_tokens=${maxTokens}) — caller should trim prompt or raise cap`);
                 }
-                // 2026-07-06: 日志打 fetch/network/parse 三段 + prompt 体积, 以后 LLM 调用慢直接看这里定位
                 const _tAfter = Date.now();
                 const promptBytes = JSON.stringify(messages).length;
-                console.log(`[pi-ai timing] total=${_tAfter - _t0}ms attempt=${attempt + 1} fetch=${_tResp - _tFetch}ms parse=${_tParse - _tResp}ms reply=${content.length}B model=${this.mapModel()} prompt=${promptBytes}B`);
+                console.log(`[pi-ai timing] total=${_tAfter - _t0}ms attempt=${attempt + 1} fetch=${_tResp - _tFetch}ms parse=${_tParse - _tResp}ms reply=${content.length}B toolCalls=${toolCalls?.length ?? 0} model=${this.mapModel()} prompt=${promptBytes}B`);
                 return { reply: content, toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined };
             }
-            // 空 content: 200 但 content="" → minimax 上游偶发, 退避后重试
             console.warn(`[pi-ai] attempt ${attempt + 1}/3: 空 content (finish_reason=${lastFinishReason}), 退避 1.5s 重试`);
             const _tSleep = Date.now();
             await new Promise(resolve => setTimeout(resolve, 1500));
             console.log(`[pi-ai timing] attempt=${attempt + 1} empty; backoff=${Date.now() - _tSleep}ms; total=${Date.now() - _t0}ms so far`);
         }
         console.warn(`[pi-ai] 3 次重试都返回空 content (finish_reason=${lastFinishReason})`);
-        return { reply: '' }; // 返回空让上层看到 [AI 服务调用失败]
+        return { reply: '' };
     }
     async callAnthropic(messages, temperature, maxTokens, signal) {
         const apiKey = this.getApiKey();
@@ -600,7 +602,8 @@ function detectModel(provider) {
         openrouter: 'anthropic/claude-sonnet-4.5',
         gemini: 'gemini-2.5-pro',
         minimax: 'MiniMax-M3',
-        deepseek: 'deepseek-chat',
+        // 2026-07-17: V3 官方下线, 迁 V4
+        deepseek: 'deepseek-v4-flash',
         kimi: 'moonshot-v1-8k',
         glm: 'glm-4-flash',
         qwen: 'qwen-plus',

package/dist/llm/tool-manifest/index.js

@@ -48,6 +48,65 @@ export function getToolsByLayer(layerId) {
  *
  * 不包含: 完整 parameters schema (那是 PiAI 客户端在调用时读)
  */
+/**
+ * 把 ToolManifest 转成 OpenAI function calling 格式 (tools 数组)
+ * 用于 native tool_choice: "auto" 模式, 让 LLM 选择调用.
+ *
+ * 注意: 递归处理嵌套参数 (type='object' 的 properties / type='array' 的 items)
+ */
+export function formatForOpenAI(tools) {
+    const list = tools ?? ALL;
+    return list.map((t) => {
+        const properties = {};
+        const required = [];
+        for (const p of t.parameters) {
+            properties[p.name] = convertParameter(p);
+            if (p.required)
+                required.push(p.name);
+        }
+        return {
+            type: 'function',
+            function: {
+                name: t.id,
+                description: t.oneLine,
+                parameters: {
+                    type: 'object',
+                    properties,
+                    required,
+                },
+            },
+        };
+    });
+}
+function convertParameter(p) {
+    const schema = { type: p.type === 'enum' ? 'string' : p.type };
+    if (p.description)
+        schema.description = p.description;
+    if (p.enumValues)
+        schema.enum = p.enumValues;
+    if (p.default !== undefined)
+        schema.default = p.default;
+    if (p.minimum !== undefined)
+        schema.minimum = p.minimum;
+    if (p.maximum !== undefined)
+        schema.maximum = p.maximum;
+    if (p.format)
+        schema.format = p.format;
+    if (p.type === 'object' && p.properties) {
+        schema.properties = {};
+        for (const sub of p.properties) {
+            schema.properties[sub.name] = convertParameter(sub);
+        }
+    }
+    if (p.type === 'array' && p.items) {
+        schema.items = convertParameter(p.items);
+        if (p.minItems !== undefined)
+            schema.minItems = p.minItems;
+        if (p.maxItems !== undefined)
+            schema.maxItems = p.maxItems;
+    }
+    return schema;
+}
 export function formatForPrompt(tools) {
     const list = tools ?? ALL;
     const lines = [

package/dist/scripts/dedup-session-messages.js

@@ -0,0 +1,68 @@
+/**
+ * 历史 session.messages 清理脚本 (2026-07-15 Bug 4 修复配套)
+ * 一次性扫描 ~/.bolloon/sessions/cache/ 下所有 session 文件, 相邻去重 (同 type+content),
+ * 写回原文件. 老数据有此 bug (client PATCH + server /message 各 push 一份 user msg)
+ * 会导致重启后"每个 user 气泡显示 2 个".
+ *
+ * 跑法:
+ *   npx tsx src/scripts/dedup-session-messages.ts [--dry-run] [--only channelId]
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+const SESSIONS_DIR = path.join(process.env.HOME || '/tmp', '.bolloon', 'sessions', 'cache');
+async function main() {
+    const args = process.argv.slice(2);
+    const dryRun = args.includes('--dry-run');
+    const onlyId = args.includes('--only') ? args[args.indexOf('--only') + 1] : null;
+    let files;
+    try {
+        files = await fs.readdir(SESSIONS_DIR);
+    }
+    catch (e) {
+        console.log(`无法读 ${SESSIONS_DIR}: ${e.message}`);
+        return;
+    }
+    console.log(`扫描 ${SESSIONS_DIR}/ (${files.length} 文件), dry-run=${dryRun}${onlyId ? `, only=${onlyId}` : ''}`);
+    let totalScanned = 0;
+    let totalFixed = 0;
+    let totalDupes = 0;
+    for (const f of files) {
+        if (!f.endsWith('.json'))
+            continue;
+        if (onlyId && !f.startsWith(onlyId))
+            continue;
+        const fp = path.join(SESSIONS_DIR, f);
+        totalScanned++;
+        try {
+            const raw = await fs.readFile(fp, 'utf8');
+            const session = JSON.parse(raw);
+            const msgs = Array.isArray(session.messages) ? session.messages : [];
+            if (msgs.length === 0)
+                continue;
+            let lastType = null;
+            let lastContent = null;
+            const deduped = msgs.filter((m) => {
+                const same = lastType === m.type && lastContent === m.content;
+                lastType = m.type;
+                lastContent = m.content;
+                return !same;
+            });
+            const dupes = msgs.length - deduped.length;
+            if (dupes === 0)
+                continue;
+            totalFixed++;
+            totalDupes += dupes;
+            console.log(`  ${f}: ${msgs.length} → ${deduped.length} (去重 ${dupes} 条)`);
+            if (!dryRun) {
+                session.messages = deduped;
+                session.lastUpdated = new Date().toISOString();
+                await fs.writeFile(fp, JSON.stringify(session, null, 2));
+            }
+        }
+        catch (e) {
+            console.warn(`  ${f} 解析失败: ${e.message?.slice(0, 100)}`);
+        }
+    }
+    console.log(`\n扫描 ${totalScanned} 文件, 修复 ${totalFixed} 个, 共去重 ${totalDupes} 条${dryRun ? ' (dry-run, 未写入)' : ''}`);
+}
+main().catch(e => { console.error('ERR:', e); process.exit(1); });

package/dist/web/client-hearth.js

@@ -0,0 +1,67 @@
+/**
+ * client-hearth.ts — judgeness 前端模块 (占位实现)
+ *
+ * 防御期: 接 routes-hearth.ts, 渲染最小骨架 UI (My Hearth / Discover / Visit).
+ * 真实样式与组件待相持期接入 bolloon 现有 ui 设计 (HIG 等参考).
+ *
+ * 这个文件会被 esbuild 打包进 dist/web/client.js (与 src/web/client.ts 一致链路).
+ *
+ * 部署约定: 本文件 import 的 url 都是 '/api/hearth/*', 与 server.ts 端口 54188 对齐.
+ */
+// 默认接受 JSON-LD (agent 头等公民); 人类用 ?view=human 切
+async function fetchHearth(path, opts = {}) {
+    const res = await fetch(path, { headers: { Accept: opts.json ? 'application/ld+json' : '*/*' } });
+    if (!res.ok)
+        throw new Error(`hearth fetch ${path} -> ${res.status}`);
+    return await res.json();
+}
+// 三视图 stub: 由主 client.ts 路由到 #/hearth / #/hearth/discover / #/hearth/visit/<pk>
+export async function renderMyHearth(root) {
+    root.innerHTML = '<h1>My Hearth</h1><p>Loading…</p>';
+    try {
+        const data = await fetchHearth('/api/hearth');
+        root.innerHTML = `
+      <h1>My Hearth</h1>
+      <dl>
+        <dt>Service</dt><dd>${data.service} v${data.version}</dd>
+        <dt>Root</dt><dd><code>${data.rootPath}</code></dd>
+        <dt>Description count</dt><dd>${data.descriptionCount}</dd>
+        <dt>Visibility channels</dt><dd>${data.visibilityChannels}</dd>
+        <dt>Allowlist count</dt><dd>${data.allowlistCount}</dd>
+        <dt>Defense mode</dt><dd>${data.defenseMode ? 'ON (write APIs disabled)' : 'OFF (反攻期)'}</dd>
+      </dl>
+      <p>视图: <a href="#/hearth/discover">Discover</a> · <a href="#/hearth/visit/__self__">Visit self</a></p>`;
+    }
+    catch (e) {
+        root.innerHTML = `<h1>My Hearth</h1><p style="color:red">Error: ${e.message}</p>`;
+    }
+}
+export async function renderDiscover(root) {
+    root.innerHTML = '<h1>Discover</h1><p>Searching…</p>';
+    try {
+        const data = await fetchHearth('/api/hearth/discover');
+        // data 可能是 JSON-LD @graph 或 list
+        const items = Array.isArray(data) ? data : (data['@graph'] ?? []);
+        const cards = items.slice(0, 50).map((it) => {
+            const id = it['@id'] ?? it.descriptionId ?? '?';
+            const vis = it.visibility ?? '?';
+            const state = it.openState ?? '?';
+            return `<li><code>${id}</code> · <span>${vis}</span> · <span>${state}</span></li>`;
+        }).join('');
+        root.innerHTML = `<h1>Discover</h1><ul>${cards || '<li>(no results)</li>'}</ul>`;
+    }
+    catch (e) {
+        root.innerHTML = `<h1>Discover</h1><p style="color:red">Error: ${e.message}</p>`;
+    }
+}
+export async function renderVisit(root, _pubkey) {
+    root.innerHTML = `<h1>Visit</h1><p>Visit 视图待相持期实现 (plan §C2).</p>`;
+}
+// 注册 router hook — 主 client.ts 在启动时调用
+export function registerHearthRoutes(router, getRoot) {
+    router.on('/hearth', () => void renderMyHearth(getRoot()));
+    router.on('/hearth/discover', () => void renderDiscover(getRoot()));
+    router.on('/hearth/visit/:pk', (_p, params) => {
+        void renderVisit(getRoot(), params['pk'] ?? '__self__');
+    });
+}