@bolloon/bolloon-agent 0.3.1 → 0.3.3

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));
+}

package/dist/judgeness/reflect.js

@@ -0,0 +1,93 @@
+/**
+ * judgeness · reflect.ts
+ *
+ * description ↔ HumanJudgment 的双向反射:
+ *   - reflectFromJudgment: 给一个 hv-id, 生成或更新对应 jd-id (5 维默认 unset, basis 空)
+ *   - mergeIntoJudgment: 给一个 jd-id, 反向把 facets 写到 judgment 的 metadata (附加, 不破坏 v0)
+ *
+ * 关键不变量: 不动 HumanJudgment 主表 schema. 所有 facets 通过 metadata.judgeness_* 字段挂上.
+ * 这样老 v0 数据可被自动视为 judgeness_v0, 零迁移.
+ */
+import { newDescriptionId, loadDescription, saveDescription, findDescriptionByJudgmentRef } from './store.js';
+/** 给定 HumanJudgment, 生成 (或更新) JudgenessDescription.
+ *  若已存在同 judgmentRef 的 jd, 则 facets/basis 合并 (覆盖优先). */
+export async function reflectFromJudgment(opts) {
+    const existing = await findDescriptionByJudgmentRef(opts.judgment.id);
+    const now = new Date().toISOString();
+    if (existing) {
+        const merged = {
+            ...existing,
+            facets: { ...existing.facets, ...(opts.facets ?? {}) },
+            basis: { ...existing.basis, ...(opts.basis ?? {}) },
+            scope: {
+                domains: opts.scopeDomains ?? existing.scope.domains,
+                topics: opts.scopeTopics ?? existing.scope.topics,
+            },
+            visibility: opts.visibility ?? existing.visibility,
+            openState: opts.openState ?? existing.openState,
+            updatedAt: now,
+            lastTransitionAt: opts.visibility && opts.visibility !== existing.visibility
+                ? now
+                : opts.openState && opts.openState !== existing.openState
+                    ? now
+                    : existing.lastTransitionAt,
+        };
+        await saveDescription(merged);
+        return merged;
+    }
+    const created = {
+        descriptionId: newDescriptionId(),
+        judgmentRef: opts.judgment.id,
+        description_version: 1,
+        facets: {
+            judgment: opts.facets?.judgment,
+            taste_aesthetic: opts.facets?.taste_aesthetic,
+            novelty_score: opts.facets?.novelty_score,
+            imaginative_score: opts.facets?.imaginative_score,
+            curiosity_vector: opts.facets?.curiosity_vector,
+        },
+        basis: {
+            taste_basis: opts.basis?.taste_basis,
+            novelty_basis: opts.basis?.novelty_basis,
+            imagination_basis: opts.basis?.imagination_basis,
+        },
+        scope: { domains: opts.scopeDomains ?? [], topics: opts.scopeTopics ?? [] },
+        visibility: opts.visibility ?? 'private',
+        openState: opts.openState ?? 'locked',
+        by: opts.by,
+        byAgentId: opts.byAgentId,
+        createdAt: now,
+        updatedAt: now,
+        lastTransitionAt: now,
+    };
+    await saveDescription(created);
+    return created;
+}
+/** 反向: 从 jd-id 合成一份 metadata 注入用的字段, 不动 HumanJudgment 主表. */
+export function deriveJudgmentMetadataPatch(jdId, jd) {
+    return {
+        judgeness_ref: jdId,
+        judgeness_card_version: jd.description_version,
+        judgeness_visibility: jd.visibility,
+        judgeness_open_state: jd.openState,
+    };
+}
+/** 给一个 hv-id 拿最新 jd (用于 judgment-protocol 的 reflect 钩子).
+ *  供 judgment-protocol.ts:463-537 reflect() 在写完 HumanJudgment 后异步触发. */
+export async function reflectAfterJudgment(judgment, by, byAgentId) {
+    // 默认: scope=topics 从 context.domain 推出, facets 全 unset.
+    return await reflectFromJudgment({
+        judgment,
+        by,
+        byAgentId,
+        scopeDomains: [judgment.context.domain],
+        scopeTopics: [judgment.context.domain],
+        visibility: 'private',
+        openState: 'locked',
+    });
+}
+/** 工具: 拿一个 jd, 返回它引用的 hv (供 audit) */
+export async function descriptionToJudgmentRef(jdId) {
+    const d = await loadDescription(jdId);
+    return d?.judgmentRef ?? null;
+}