@bolloon/bolloon-agent 0.3.1 → 0.3.4

package/dist/agents/pi-sdk-session-manager.js

@@ -2,7 +2,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { getGlobalSharedContext } from '../social/global-shared-context.js';
 import { Session, saveSession, loadSession } from '@bolloon/constraint-runtime';
-const SHARED_SESSION_PATH = path.join(process.env.HOME || '/tmp', '.bolloon', 'sessions');
+import { SHARED_SESSION_PATH } from '../web/server-types.js';
 const PERSONA_PATH = path.join(process.env.HOME || '/tmp', '.bolloon', 'persona.json');
 /**
  * PiSessionManager — 负责:

package/dist/agents/pi-sdk.js

@@ -842,11 +842,24 @@ ${this.getToolDefinitions()}
         //   真正折叠需要把 pi-sdk 历史灌回 pivot 的 history 数组 — 侵入较大.
         //   当前 priority: 临时传空实现, 让 budget 公式放够 (workflow-pivot-loop.ts line 220)
         //   不再撞预算. 这条路径留作技术债.
+        // 2026-07-17 Bug 1 修: 注入 messageHistory (hydrateMessageHistory 从 session JSON 回灌的) 到 system prompt
+        //   pivot loop execute() 内部自己维护 messageHistory, 跟 pi-sdk 的 this.messageHistory 隔离,
+        //   不注入的话 LLM 看不到历史对话, 每次都是新对话.
+        const historyLines = [];
+        const historyToInject = this.messageHistory.slice(-20, -1);
+        for (const m of historyToInject) {
+            const roleLabel = m.role === 'user' ? '用户' : m.role === 'assistant' ? '你' : m.role === 'tool' ? '工具结果' : m.role;
+            const text = (m.content || '').slice(0, 2000);
+            if (text)
+                historyLines.push(`[${roleLabel}]: ${text}`);
+        }
+        const historyBlock = historyLines.length > 0
+            ? `\n\n【历史对话 (最近 ${historyLines.length} 条)】\n${historyLines.join('\n')}\n【历史对话结束】`
+            : '';
         const onCompact = async () => {
             // no-op (best-effort hook for future pi-sdk/pivot history sync)
         };
-        const result = await loop.execute(input, llm, systemPrompt, this.currentOnStream ?? undefined, this.currentSignal ?? undefined, onCompact);
-        this.messageHistory.push({ role: 'user', content: input });
+        const result = await loop.execute(input, llm, systemPrompt + historyBlock, this.currentOnStream ?? undefined, this.currentSignal ?? undefined, onCompact);
         if (result.response) {
             this.messageHistory.push({ role: 'assistant', content: result.response });
         }
@@ -1000,7 +1013,9 @@ ${toolDefs}
             //   2. reactive compaction (prompt 估算超阈值, 跑压缩)
             //   3. prompt-too-long (LLM 报错 4xxx token 错误, 跑 reactive compaction 再试 1 次)
             // 失败静默: 全部重试失败 → 空 reply (上层用 no tool_use 终止)
-            const response = await this.callLlmWithRecovery(llm, messages, systemPrompt, signal, onStream);
+            // Bug 5: pass tool IDs for native OpenAI tool calling
+            const toolIds = Array.from(this.tools.keys());
+            const response = await this.callLlmWithRecovery(llm, messages, systemPrompt, signal, onStream, toolIds);
             const reply = (response.reply || '').trim();
             // 2026-06-30: OpenAI 协议 native tool_calls (LLM 真产了 tool_call 时, minimax/M3 会返回 id)
             const nativeToolCalls = response.toolCalls;
@@ -1067,11 +1082,39 @@ ${toolDefs}
             // 2026-06-19 架构 fix: parseToolCall 优先于 isFinalResponse
             //   之前: 思考块里的 "<final gen>" 触发 isFinalResponse 提前 break, 工具从未真正执行
             //   现在: 先尝试解析 tool_call, 有就执行; 没有才检查是不是真正的 final gen
-            const toolCall = this.parseToolCall(reply);
+            // Bug 5 (2026-07-17): 优先用 LLM 的 native tool_calls (response.toolCalls), 再回退到文本解析
+            //   deepseek-v4-flash 用 OpenAI 协议 tools 时, 会真返回结构化 tool_calls 数组
+            //   之前 nativeToolCalls 被读了不用, 只查 reply 文本, 导致 LLM 明明选了工具但代码找不到
+            let toolCall = null;
+            if (nativeToolCalls && nativeToolCalls.length > 0) {
+                const nc = nativeToolCalls[0];
+                // OpenAI 协议: { id, type: 'function', function: { name, arguments: JSON string } }
+                // 转换成 internal { name, args, id }
+                try {
+                    const args = typeof nc.function?.arguments === 'string'
+                        ? JSON.parse(nc.function.arguments)
+                        : (nc.function?.arguments || {});
+                    toolCall = {
+                        name: nc.function?.name,
+                        args,
+                        id: nc.id || `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+                    };
+                    console.log(`[PiAgent] 用 native tool_call: ${toolCall.name} (id=${toolCall.id})`);
+                }
+                catch (err) {
+                    console.warn(`[PiAgent] 解析 native tool_call 失败, 回退到文本解析: ${err.message?.slice(0, 100)}`);
+                    toolCall = null;
+                }
+            }
+            if (!toolCall) {
+                toolCall = this.parseToolCall(reply);
+            }
             // 2026-06-30 修: 给 toolCall 分配稳定 id, 让后续 tool result 能引用同一个 id
             //   OpenAI 协议要求 messages 里 tool result 必须有对应的 tool_call_id, 否则 400
-            if (toolCall) {
+            if (toolCall && !toolCall.id) {
                 toolCall.id = `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+            }
+            if (toolCall) {
                 this.messageHistory.push({
                     role: 'assistant',
                     content: reply,
@@ -1526,10 +1569,14 @@ Workspace root folder: ${this.cwd}
                 //   bolloon 之前把所有 tool result 包成 "[工具结果] ..." 当 user/assistant role 发, minimax 严格校验失败
                 //   现在: 保留 role='tool' + 加 tool_call_id 字段 (用 messageHistory 里自己生成的 id)
                 if (role === 'tool') {
-                    const result = m.toolResult ? JSON.stringify(m.toolResult) : content;
-                    content = `[工具结果] ${result}`;
-                    // MiniMax 等 API 不支持 tool role, 转为 user role
-                    out.push({ role: 'user', content });
+                    const toolCallId = m.toolCallId || m.toolCall?.id || '';
+                    const result = m.toolResult;
+                    out.push({
+                        role: 'tool',
+                        content: result ? (typeof result === 'string' ? result : JSON.stringify(result)) : content,
+                        tool_call_id: toolCallId,
+                        name: m.toolCall?.name || '',
+                    });
                     continue;
                 }
                 // system role (router hint 等) 直接保留
@@ -1593,7 +1640,7 @@ Workspace root folder: ${this.cwd}
      *
      * 失败静默: 全部失败 → 返回空 reply, 让上层 no-tool_use 终止
      */
-    async callLlmWithRecovery(llm, contextOrMessages, systemPrompt, signal, onStream) {
+    async callLlmWithRecovery(llm, contextOrMessages, systemPrompt, signal, onStream, tools) {
         // Reactive compaction 预检: 估算 token 超 80% 阈值, 跑一次
         const estimated = this.estimateHistoryTokens();
         if (estimated > this.MAX_OUTPUT_TOKEN_ESCALATION_THRESHOLD * 0.8) {
@@ -1646,7 +1693,8 @@ Workspace root folder: ${this.cwd}
             try {
                 // M3.5 (2026-06-17): 传 messages 数组 (如果 contextOrMessages 是数组) 或字符串
                 //   数组版让 LLM 看到结构化的 user/assistant/tool role, 而不是把 history 拼成单字符串
-                const response = await llm.chat(contextOrMessages, systemPrompt, signal);
+                // Bug 5: pass tool IDs for native OpenAI tool calling
+                const response = await llm.chat(contextOrMessages, systemPrompt, signal, tools);
                 // 2026-06-30: 透传 toolCalls (OpenAI 协议 native) 给上层, 让 assistant message 能 emit 真 id
                 return { reply: response.reply || '', toolCalls: response.toolCalls };
             }

package/dist/bootstrap/remote-mirror.js

@@ -15,11 +15,43 @@
  * 触发:
  *   - server.ts: agent.history.get.reply handler 写完 → mirrorRemoteHistory
  *   - client.ts: openRemoteChannelChat → loadRemoteHistory 优先读镜像
+ *
+ * 2026-07-17: 加写盘重试 → 短暂文件系统抖动不吞消息
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
 import { saveWindow as saveSessionWindow } from './session-window.js';
+// ============== 重试 ==============
+const MIRROR_RETRIES = 3;
+const MIRROR_BACKOFF_MS = 200;
+const MAX_BACKOFF_MS = 3000;
+const RETRYABLE_CODES = new Set([
+    'EBUSY', 'EAGAIN', 'EMFILE', 'ENFILE', 'ENOSPC', 'EIO',
+]);
+function isRetryable(e) {
+    if (!e || typeof e !== 'object')
+        return false;
+    const code = e.code || '';
+    return RETRYABLE_CODES.has(code);
+}
+async function withRetry(fn, label) {
+    for (let attempt = 0; attempt <= MIRROR_RETRIES; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            if (attempt < MIRROR_RETRIES && isRetryable(e)) {
+                const ms = Math.min(MIRROR_BACKOFF_MS * Math.pow(2, attempt), MAX_BACKOFF_MS);
+                console.warn(`[mirror] ${label} 失败 (attempt ${attempt + 1}/${MIRROR_RETRIES}), ${ms}ms 后重试: ${e?.message || e}`);
+                await new Promise(r => setTimeout(r, ms));
+                continue;
+            }
+            throw e;
+        }
+    }
+    throw new Error(`unreachable: ${label}`);
+}
 // ============== 路径 ==============
 function sanitize(s) {
     return s.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
@@ -37,14 +69,14 @@ export function getRemoteMirrorWindowPath(targetPublicKey, channelId, home) {
 // ============== 写入 ==============
 /**
  * 把 A 端的 history 镜像到 B 端本地. atomic (单文件 writeFile, 中途崩溃顶多旧版本留下).
- * 失败静默不阻塞 RPC reply 返回.
+ * 失败自动重试 MIRROR_RETRIES 次 (暂态文件系统错误), 最终失败静默不阻塞 RPC reply.
  */
 export async function mirrorRemoteHistory(opts) {
     try {
         const home = opts.home || os.homedir();
         const mirrorPath = getRemoteMirrorPath(opts.targetPublicKey, opts.channelId, home);
         const windowPath = getRemoteMirrorWindowPath(opts.targetPublicKey, opts.channelId, home);
-        await fs.mkdir(path.dirname(mirrorPath), { recursive: true });
+        await withRetry(() => fs.mkdir(path.dirname(mirrorPath), { recursive: true }), 'mkdir');
         // 主体镜像
         const payload = {
             channelId: opts.channelId,
@@ -54,12 +86,13 @@ export async function mirrorRemoteHistory(opts) {
             lastUpdated: opts.lastUpdated || new Date().toISOString(),
             mirroredAt: new Date().toISOString(),
         };
-        await fs.writeFile(mirrorPath, JSON.stringify(payload, null, 2), 'utf-8');
+        await withRetry(() => fs.writeFile(mirrorPath, JSON.stringify(payload, null, 2), 'utf-8'), 'write mirror');
         // 窗口联动
-        await saveSessionWindow(opts.channelId, `remote-${opts.targetPublicKey.slice(0, 12)}`, opts.messages, { home, windowSize: 30 });
+        await withRetry(() => saveSessionWindow(opts.channelId, `remote-${opts.targetPublicKey.slice(0, 12)}`, opts.messages, { home, windowSize: 30 }), 'write window');
         return { ok: true, mirrorPath, windowPath };
     }
     catch (e) {
+        console.warn(`[mirror] 最终失败: ${e?.message || e}`);
         return { ok: false, error: e?.message || String(e) };
     }
 }

package/dist/judgeness/auto-add.js

@@ -0,0 +1,145 @@
+/**
+ * judgeness · auto-add.ts — Channel-based Auto-add (反攻期 O3)
+ *
+ * 用户原话: "传播智能体的时候, 智能体可根据内容频道选择其他用户的 Id 自动添加"
+ *
+ * 流程:
+ *   1. POST /api/hearth/channel-autoadd { channelTopic, sourceChannelOwnerPk? }
+ *   2. 闸 2 (allowlist gate) 校验 sourceChannelOwnerPk
+ *   3. 扫描 ~/.bolloon/judgeness/descriptions/, 找出 scope.topics 含 channelTopic 且 openState='open' 的 description
+ *   4. 对每个 description 的 owner pk 调用 p2p-direct.joinTopic
+ *   5. 全部进 ~/.bolloon/human-values/counterfactual-audit.jsonl
+ *   6. 频次限制 (defense=无; 反攻期 = 每分钟 5 次; 单 peer pk 24h 内最多 10 次)
+ *
+ * 反攻期接 src/network/p2p-direct.ts 的 joinTopic; 防御期 stub.
+ * 反攻期接 src/judgeness/protocol.ts 的 sendAutoaddInvite.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+const DEFENSE_FREQ_LIMIT_PER_HOUR = 5; // 防御期更严
+const ROLLING_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+export async function performAutoAdd(req, opts = {}) {
+    if (!req.channelTopic)
+        throw new Error('channelTopic required');
+    const now = opts.nowMs ?? Date.now();
+    // ---- 频次限制 (读 audit log last hour 统计) ----
+    const auditLog = await readAutoaddAudit();
+    const recent = auditLog.filter((l) => now - l.ts < ROLLING_WINDOW_MS);
+    if (recent.length >= DEFENSE_FREQ_LIMIT_PER_HOUR) {
+        return {
+            channelTopic: req.channelTopic,
+            matched: 0,
+            joined: 0,
+            skipped: 0,
+            auditLines: [],
+            frequencyLimited: true,
+        };
+    }
+    // ---- 扫描 descriptions 找 matches ----
+    const { listDescriptions } = await import('./store.js');
+    const descs = await listDescriptions();
+    const matched = descs.filter((d) => {
+        const open = d.openState === 'open';
+        const topicMatch = (d.scope.topics ?? []).includes(req.channelTopic);
+        return open && topicMatch;
+    });
+    // ---- join (defense=stub) ----
+    const result = {
+        channelTopic: req.channelTopic,
+        matched: matched.length,
+        joined: 0,
+        skipped: 0,
+        auditLines: [],
+        frequencyLimited: false,
+    };
+    // 每次请求都写一条 audit line (不论 matched), 这样 frequency limit 才能工作
+    result.auditLines.push(JSON.stringify({
+        ts: now,
+        kind: 'autoadd_request',
+        channelTopic: req.channelTopic,
+        by: undefined,
+        matched: matched.length,
+    }));
+    for (const d of matched) {
+        const ownerPk = d.byAgentId ?? '__no-pk__';
+        if (!opts.joinTopic) {
+            // defense: 仅 audit, 不调用 joinTopic
+            result.skipped += 1;
+            const line = JSON.stringify({
+                ts: now,
+                kind: 'autoadd_skipped',
+                channelTopic: req.channelTopic,
+                descriptionId: d.descriptionId,
+                ownerPk,
+                reason: 'defense stub',
+            });
+            result.auditLines.push(line);
+            continue;
+        }
+        const r = await opts.joinTopic(req.channelTopic, ownerPk);
+        if (r.ok) {
+            result.joined += 1;
+            result.auditLines.push(JSON.stringify({
+                ts: now,
+                kind: 'autoadd_joined',
+                channelTopic: req.channelTopic,
+                descriptionId: d.descriptionId,
+                ownerPk,
+            }));
+        }
+        else {
+            result.skipped += 1;
+            result.auditLines.push(JSON.stringify({
+                ts: now,
+                kind: 'autoadd_join_failed',
+                channelTopic: req.channelTopic,
+                descriptionId: d.descriptionId,
+                ownerPk,
+            }));
+        }
+    }
+    // ---- 写 audit log ----
+    await appendCounterfactualAudit(result.auditLines);
+    return result;
+}
+// ---------------------------------------------------------------------------
+// audit 读写 helpers
+// ---------------------------------------------------------------------------
+async function readAutoaddAudit() {
+    const auditPath = await auditPathResolved();
+    try {
+        const raw = await fs.readFile(auditPath, 'utf-8');
+        return raw.split('\n').filter(Boolean).map((l) => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            }
+        }).filter((x) => !!x);
+    }
+    catch {
+        return [];
+    }
+}
+async function appendCounterfactualAudit(lines) {
+    if (lines.length === 0)
+        return;
+    const auditPath = await auditPathResolved();
+    const dir = path.dirname(auditPath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.appendFile(auditPath, lines.join('\n') + '\n', 'utf-8');
+}
+let _auditPathCache = null;
+async function auditPathResolved() {
+    if (_auditPathCache)
+        return _auditPathCache;
+    const home = process.env.BOLLOON_HOME || path.join(os.homedir(), '.bolloon');
+    _auditPathCache = path.join(home, 'human-values', 'counterfactual-audit.jsonl');
+    return _auditPathCache;
+}
+// 工具: 复位 cache (测试用)
+export function _resetAuditPathCacheForTest() {
+    _auditPathCache = null;
+}

package/dist/judgeness/protocol.js

@@ -0,0 +1,214 @@
+/**
+ * judgeness · protocol.ts
+ *
+ * 4 新 P2P kind (扩展 judgment-protocol 的 Kind 枚举):
+ *   - hearth_description_publish: A 告知 B "我公开了 jd <id>"
+ *   - hearth_description_query:    A 向 B 询问 jd <id> 正文
+ *   - hearth_autoadd_invite:      A 邀请 B 加入 channel <topic>
+ *   - hearth_block:               A 屏蔽 B / 某 channel
+ *
+ * 复用 src/agents/judgment-protocol.ts 的 listener 安装模式 (174-194).
+ * Transport 仍走 IrohTransport (不另起), 复用 sendMessage.
+ *
+ * 防御期 (现在 → 6 月):
+ *   - 此文件已发布, 但 4 kind 仅在 enum 占位; 不会发帧.
+ *   - 相持期开始才真正调用 sendMessage.
+ */
+import { EventEmitter } from 'events';
+import { irohTransport as defaultIrohTransport } from '../network/iroh-transport.js';
+import { resolveGate2, resolveGate3 } from './visibility.js';
+class HearthEventBus extends EventEmitter {
+}
+export const hearthEventBus = new HearthEventBus();
+// ---------------------------------------------------------------------------
+// 帧构造 / 解析
+// ---------------------------------------------------------------------------
+function encode(f) {
+    return new TextEncoder().encode(JSON.stringify({ kind: f.kind, payload: f.payload, ts: f.payload.ts }));
+}
+function decode(buf) {
+    try {
+        const obj = JSON.parse(new TextDecoder().decode(buf));
+        if (!obj?.kind || !obj.payload)
+            return null;
+        if (!isHearthKind(obj.kind))
+            return null;
+        return obj;
+    }
+    catch {
+        return null;
+    }
+}
+function isHearthKind(k) {
+    return (k === 'hearth_description_publish' ||
+        k === 'hearth_description_query' ||
+        k === 'hearth_autoadd_invite' ||
+        k === 'hearth_block');
+}
+// ---------------------------------------------------------------------------
+// 协议硬约束 (发送前 throw)
+// ---------------------------------------------------------------------------
+/** 在调用 transport.sendMessage 前必跑一次 */
+export function validateFrameBeforeSend(frame) {
+    const p = frame.payload;
+    switch (frame.kind) {
+        case 'hearth_description_publish':
+            if (!p.descriptionId)
+                throw new Error('hearth_description_publish: descriptionId required');
+            if (!p.visibility)
+                throw new Error('hearth_description_publish: visibility required');
+            break;
+        case 'hearth_description_query':
+            if (!p.descriptionId)
+                throw new Error('hearth_description_query: descriptionId required');
+            break;
+        case 'hearth_autoadd_invite':
+            if (!p.channelTopic)
+                throw new Error('hearth_autoadd_invite: channelTopic required');
+            if (p.visibility === 'private')
+                throw new Error('hearth_autoadd_invite: visibility=private forbidden');
+            break;
+        case 'hearth_block':
+            if (p.targetNodeId === p.fromNodeId)
+                throw new Error('hearth_block: cannot block self');
+            break;
+    }
+}
+const states = new WeakMap();
+function getState(t) {
+    let s = states.get(t);
+    if (!s) {
+        s = { listenersInstalled: false };
+        states.set(t, s);
+    }
+    return s;
+}
+export function ensureHearthListeners(transport = defaultIrohTransport) {
+    const s = getState(transport);
+    if (s.listenersInstalled)
+        return;
+    s.listenersInstalled = true;
+    transport.onMessage('hearth_description_publish', async (msg) => {
+        const f = decode(msg.payload);
+        if (!f || f.kind !== 'hearth_description_publish')
+            return;
+        const p = f.payload;
+        hearthEventBus.emit('event', { kind: 'publish_received', publishId: p.publishId, fromNodeId: p.fromNodeId });
+        await onPublishReceived(transport, p);
+    });
+    transport.onMessage('hearth_description_query', async (msg) => {
+        const f = decode(msg.payload);
+        if (!f || f.kind !== 'hearth_description_query')
+            return;
+        const p = f.payload;
+        hearthEventBus.emit('event', { kind: 'query_received', queryId: p.queryId, fromNodeId: p.fromNodeId, descriptionId: p.descriptionId });
+        await onQueryReceived(transport, p);
+    });
+    transport.onMessage('hearth_autoadd_invite', async (msg) => {
+        const f = decode(msg.payload);
+        if (!f || f.kind !== 'hearth_autoadd_invite')
+            return;
+        const p = f.payload;
+        hearthEventBus.emit('event', { kind: 'invite_received', inviteId: p.inviteId, fromNodeId: p.fromNodeId, channelTopic: p.channelTopic });
+        await onAutoaddInviteReceived(transport, p);
+    });
+    transport.onMessage('hearth_block', async (msg) => {
+        const f = decode(msg.payload);
+        if (!f || f.kind !== 'hearth_block')
+            return;
+        const p = f.payload;
+        hearthEventBus.emit('event', { kind: 'block_received', blockId: p.blockId, fromNodeId: p.fromNodeId, targetNodeId: p.targetNodeId });
+        await onBlockReceived(p);
+    });
+}
+// ---------------------------------------------------------------------------
+// Listener handlers (实现都先 stub, 等相持期再接 store / p2p-direct)
+// ---------------------------------------------------------------------------
+async function onPublishReceived(_t, _p) {
+    // TODO(相持期): 校验 fromNodeId 在 allowlist 内, 然后 fetch cache
+}
+async function onQueryReceived(_t, _p) {
+    // TODO(相持期): 闸 3 后, 把对应 description 走 visibility scrubber 后回发
+}
+async function onAutoaddInviteReceived(_t, p) {
+    // 闸 2: 检查 fromNodeId 是否在 allowlist, 且 channel 隐私策略兼容
+    const ctx = { pubkey: p.fromNodeId, role: 'agent', channelTopic: p.channelTopic };
+    const g2 = await resolveGate2(p.fromNodeId, p.channelTopic);
+    if (!g2.allow) {
+        // 自动回一个 block
+        await sendBlock(_t, p.fromNodeId, p.channelTopic);
+    }
+}
+async function onBlockReceived(p) {
+    // TODO(相持期): 加入 inbound 黑名单, 后续入站全 reject
+    void p;
+}
+// ---------------------------------------------------------------------------
+// 发送接口 (相持期 / 反攻期主用)
+// ---------------------------------------------------------------------------
+export async function sendPublish(transport, descriptionId, toNodeId, visibility, channelTopic) {
+    const frame = {
+        kind: 'hearth_description_publish',
+        payload: {
+            publishId: `pub-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            fromNodeId: toNodeId, // 占位: 真实发送时本方 nodeId 由 transport 提供, 这里用目标
+            descriptionId,
+            visibility,
+            channelTopic,
+            ts: Date.now(),
+        },
+    };
+    validateFrameBeforeSend(frame);
+    await transport.sendMessage(toNodeId, frame.kind, encode(frame));
+    hearthEventBus.emit('event', { kind: 'publish_sent', publishId: frame.payload.publishId, peer: toNodeId });
+}
+export async function sendQuery(transport, descriptionId, toNodeId) {
+    const frame = {
+        kind: 'hearth_description_query',
+        payload: {
+            queryId: `q-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            fromNodeId: toNodeId,
+            descriptionId,
+            ts: Date.now(),
+        },
+    };
+    validateFrameBeforeSend(frame);
+    await transport.sendMessage(toNodeId, frame.kind, encode(frame));
+}
+export async function sendAutoaddInvite(transport, channelTopic, toNodeId, visibility = 'allowlist') {
+    const frame = {
+        kind: 'hearth_autoadd_invite',
+        payload: {
+            inviteId: `inv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            fromNodeId: toNodeId,
+            channelTopic,
+            visibility,
+            ts: Date.now(),
+        },
+    };
+    validateFrameBeforeSend(frame);
+    await transport.sendMessage(toNodeId, frame.kind, encode(frame));
+    hearthEventBus.emit('event', { kind: 'invite_sent', inviteId: frame.payload.inviteId, peer: toNodeId });
+}
+export async function sendBlock(transport, targetNodeId, channelTopic, fromNodeId = '__self__') {
+    const frame = {
+        kind: 'hearth_block',
+        payload: {
+            blockId: `blk-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            fromNodeId,
+            targetNodeId,
+            channelTopic,
+            ts: Date.now(),
+        },
+    };
+    validateFrameBeforeSend(frame);
+    await transport.sendMessage(targetNodeId, frame.kind, encode(frame));
+}
+// ---------------------------------------------------------------------------
+// 防御期唯一可对外暴露的健康查询 (无 IO)
+// ---------------------------------------------------------------------------
+export function listHearthKinds() {
+    return ['hearth_description_publish', 'hearth_description_query', 'hearth_autoadd_invite', 'hearth_block'];
+}
+// 关闭 lint: resolveGate3 未在本文件直用, 给相持期 protocol listener 用
+void resolveGate3;

package/dist/judgeness/rank.js

@@ -0,0 +1,78 @@
+/**
+ * judgeness · rank.ts — Discover 排名算法 (反攻期 O2)
+ *
+ * 设计原则 (与 plan §DISCOVER-RANKING 一致):
+ *   - 可解释, 不黑盒
+ *   - 4 因子线性: rank_score = a*recency + b*breadth + c*depth + d*trust
+ *   - 权重可调 (visibility.yaml.ranking 段; 缺省 0.4/0.2/0.2/0.2)
+ *   - 每条 ranked 项带 why 字段解释
+ *
+ * 防御期: 此文件已写, 但 routes-hearth.ts 的 /discover 还没接它 (DEFENSE_MODE).
+ */
+export const DEFAULT_RANK_WEIGHTS = {
+    recency: 0.4,
+    breadth: 0.2,
+    depth: 0.2,
+    trust: 0.2,
+};
+/** 主函数. */
+export function rankDescriptions(descs, opts = {}) {
+    const w = opts.weights ?? DEFAULT_RANK_WEIGHTS;
+    const recencyWindow = opts.recencyWindow ?? 30 * 24 * 60 * 60 * 1000;
+    const now = opts.nowMs ?? Date.now();
+    const trusted = opts.trustedPks ?? new Set();
+    const ownerMap = opts.ownerPkMap ?? new Map();
+    const out = [];
+    for (const d of descs) {
+        const recency = computeRecency(d, now, recencyWindow);
+        const breadth = computeBreadth(d);
+        const depth = computeDepth(d);
+        const ownerPk = ownerMap.get(d.descriptionId) ?? '__unknown__';
+        const trust = trusted.has(ownerPk) ? 1 : 0.3; // 不是 allowlist 也有 0.3 base score (public 维度)
+        const score = w.recency * recency + w.breadth * breadth + w.depth * depth + w.trust * trust;
+        out.push({
+            description: d,
+            rankScore: clamp01(score),
+            why: { recency, breadth, depth, trust },
+        });
+    }
+    // 排序: rankScore desc, recency desc tiebreaker
+    out.sort((a, b) => {
+        if (b.rankScore !== a.rankScore)
+            return b.rankScore - a.rankScore;
+        return b.description.createdAt.localeCompare(a.description.createdAt);
+    });
+    return out;
+}
+// ---- 子函数 (可单测) ----
+export function computeRecency(d, now, window) {
+    const t = Date.parse(d.createdAt);
+    if (!Number.isFinite(t))
+        return 0;
+    const age = Math.max(0, now - t);
+    if (age >= window)
+        return 0;
+    return 1 - age / window;
+}
+export function computeBreadth(d) {
+    const topics = new Set(d.scope.topics ?? []);
+    const domains = new Set(d.scope.domains ?? []);
+    const all = new Set([...topics, ...domains]);
+    // 3 = 满分 (覆盖广)
+    return clamp01(all.size / 3);
+}
+export function computeDepth(d) {
+    const facets = d.facets ?? {};
+    const filled = ['judgment', 'taste_aesthetic', 'novelty_score', 'imaginative_score', 'curiosity_vector']
+        .filter((k) => facets[k] !== undefined && facets[k] !== null).length;
+    // 5 维满分 1; 加 basis 文本可冲 1.2 (clamp 1)
+    const basis = d.basis ?? {};
+    const basisBonus = ['taste_basis', 'novelty_basis', 'imagination_basis']
+        .filter((k) => typeof basis[k] === 'string' && basis[k].length > 5).length;
+    return clamp01(filled / 5 + basisBonus * 0.06);
+}
+function clamp01(x) {
+    if (!Number.isFinite(x))
+        return 0;
+    return Math.max(0, Math.min(1, x));
+}