@bolloon/bolloon-agent 0.5.0 → 0.5.2

package/README.md

@@ -91,6 +91,32 @@ npm start
 
 ---
 
+## Docker
+
+不想在本机装 Node 与依赖, 可以直接跑容器 (多阶段镜像 · 非 root 用户 uid 1001 · 状态全部落在卷里):
+
+```bash
+docker build -t bolloon-agent:0.5.1 .
+docker run -d --name bolloon-agent \
+  -p 127.0.0.1:54188:54188 \
+  -v bolloon-data:/home/bolloon/.bolloon \
+  bolloon-agent:0.5.1 --web
+# → http://127.0.0.1:54188
+
+docker compose up -d                            # 同上的 compose 写法
+docker compose run --rm bolloon-cli --version   # 一次性 CLI (不用起服务)
+```
+
+- **密钥别写进 compose**: 复制 `.env.example` → `.env.docker` (已在 `.gitignore`), 或者把本机
+  0600 的 `llm-config.json` **只读挂载**进容器 (更安全: 不进环境变量、不进 `docker inspect`)。
+- **数据卷里有身份私钥与 API key 配置** (`/home/bolloon/.bolloon`): 别导出、别提交、别 `docker commit`。
+- 端口只认环境变量 `PORT` (默认 `54188`); `--port` 参数无效。
+
+完整说明 (镜像怎么搭的 · 卷与 uid 权限 · HEALTHCHECK 探什么/不探什么 · 常见问题) 见
+[docs/wiki/docker-deployment.md](./docs/wiki/docker-deployment.md)。
+
+---
+
 ## 环境变量
 
 | 变量 | 说明 |
@@ -136,6 +162,19 @@ bolloon --help     # All commands
 
 Requires Node.js ≥ 18 and an LLM API key (`OPENAI_API_KEY` or `DEEPSEEK_API_KEY`).
 
+### Docker
+
+Run it in a container instead (multi-stage image, non-root user, state in a volume):
+
+```bash
+docker build -t bolloon-agent:0.5.1 .
+docker run -d --name bolloon-agent -p 127.0.0.1:54188:54188 \
+  -v bolloon-data:/home/bolloon/.bolloon bolloon-agent:0.5.1 --web
+```
+
+Copy `.env.example` to `.env.docker` (gitignored) for keys, or mount your `llm-config.json` read-only
+(safer). Full guide: [docs/wiki/docker-deployment.md](./docs/wiki/docker-deployment.md).
+
 ### License
 
 This project is released under the [MIT License](./LICENSE). You are free to use, modify, and distribute this project, provided that you retain the copyright and permission notices. See the [LICENSE](./LICENSE) file for details.

package/dist/agents/agent-lang.js

@@ -0,0 +1,101 @@
+/**
+ * agents/agent-lang - 智能体交流语言的**声明层**与消息封装层接线
+ *
+ * 这一层只做三件事:
+ *   ① 声明: manifest 里带上 `supportedLangs` (本机支持哪些语言);
+ *   ② 出站: 拿"本机声明 + 对端声明"裁决 → 要么真编 (双方 efficode), 要么原文直发;
+ *   ③ 入站: 只按对端**声明**的语言分派 —— 声明不是 efficode 的载荷一律不进解码器。
+ *
+ * 不支持的场景怎么处理 (照 leo 的要求, 不许静默):
+ *   - 对端没声明 / 只声明 natural → 自然语言, 记一笔 `fallback=false`
+ *   - 本机想要 efficode 但对端没声明 → 回落, 记一笔 `fallback=true` + 原因
+ *   - 对端声明了本机不认识的语言字符串 → 回落, 原样呈现, 记 `unknownSide`
+ *   - 对端声明 efficode 但本机没声明支持 → 拒绝解码并抛 (绝不硬解)
+ */
+import { decodeFromPeer, encodeForPeer, defaultDeclaredLang, negotiateLang, recordLangDecision, unknownLangNames, } from '../efficode/negotiate.js';
+import { normalizeLang } from '../efficode/index.js';
+/** 本机支持的语言声明 (进程内, 由 manifest 装配处设置) */
+let localLangs = [];
+/** 本机默认声明 (env 可覆盖; 默认 natural) */
+let defaultLang = null;
+export function setLocalSupportedLangs(langs) {
+    const arr = Array.isArray(langs) ? langs : langs == null ? [] : [langs];
+    localLangs = arr.map((x) => String(x).trim()).filter(Boolean);
+    return localLangs;
+}
+export function getLocalSupportedLangs() {
+    return [...localLangs];
+}
+/** 本机声明 (没显式设置就回落到 env/默认; 声明不变量绝不"猜"成 efficode) */
+export function localDeclaredLang(env = process.env) {
+    if (defaultLang)
+        return defaultLang;
+    return defaultDeclaredLang(env);
+}
+export function setLocalDeclaredLang(lang) {
+    defaultLang = normalizeLang(lang);
+    return defaultLang ?? 'natural';
+}
+/** 本机要写进 manifest 的声明: 显式语言列表优先, 否则 [默认声明] */
+export function manifestLangDeclaration(env = process.env) {
+    if (localLangs.length)
+        return [...localLangs];
+    return [localDeclaredLang(env)];
+}
+/** 从 manifest 里读对端声明 (老 manifest 没这个字段 → 空数组 = 没声明) */
+export function peerLangsOf(manifest) {
+    const raw = manifest?.supportedLangs;
+    const arr = Array.isArray(raw) ? raw : raw == null ? [] : [raw];
+    return arr.map((x) => String(x).trim()).filter(Boolean);
+}
+/**
+ * 出站消息: 双方声明都是 efficode 才编码, 否则原文直发并在帧里如实声明 `lang: 'natural'`。
+ */
+export function buildAgentMessage(opts) {
+    const mine = opts.mine ?? manifestLangDeclaration(opts.env);
+    const enc = encodeForPeer({ text: opts.text, mine, theirs: opts.theirs, from: opts.from, op: opts.op });
+    const frame = {
+        type: 'agent_message',
+        payload: { text: enc.text, lang: enc.lang },
+        ts: Date.now(),
+        fromDid: opts.from ?? '',
+        ...(opts.to ? { toDid: opts.to } : {}),
+    };
+    recordLangDecision(enc.decision, { channel: 'agent_message', peer: opts.to });
+    return { frame: JSON.stringify(frame), lang: enc.lang, decision: enc.decision, bytes: enc.bytes, encoded: enc.lang === 'efficode' };
+}
+/** 解析线上帧 (非 agent_message / 坏 JSON → null; 不抛, 调用方按"不是我的帧"处理) */
+export function parseAgentMessageFrame(text) {
+    try {
+        const v = JSON.parse(text);
+        if (!v || v.type !== 'agent_message' || !v.payload || typeof v.payload.text !== 'string')
+            return null;
+        return v;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 入站消息: 严格按帧里 `lang` 分派。
+ * - `lang: 'efficode'` 且本机也声明 efficode → 真解包 (畸形包抛 EfficodeError)
+ * - 其它一切 (含缺字段 / 未知字符串) → 原样文本 + 明确 note, **不进解码器**
+ */
+export function readAgentMessage(frameText, opts = {}) {
+    const frame = parseAgentMessageFrame(frameText);
+    if (!frame)
+        return null;
+    const mine = opts.mine ?? manifestLangDeclaration(opts.env);
+    const declared = frame.payload.lang;
+    const inc = decodeFromPeer({ payload: frame.payload.text, declaredLang: declared, mine });
+    const decision = negotiateLang(mine, declared);
+    recordLangDecision(decision, { channel: 'agent_message_recv' });
+    return {
+        ...inc,
+        declared: inc.declaredRaw,
+        unknownLangs: unknownLangNames(declared),
+        fromDid: frame.fromDid ?? '',
+        toDid: frame.toDid,
+        decision,
+    };
+}

package/dist/agents/agent-manifest-protocol.js

@@ -54,6 +54,10 @@ export function setLocalManifest(m) {
         localManifest.exportments = [];
     if (!('sciences' in m))
         localManifest.sciences = [];
+    // 2026-09-28: 交流语言声明同规矩 —— 不给就显式清空, 免得旧的 efficode 声明在对端已经不支持时还留着.
+    // (老 manifest 语义不变: 没有 supportedLangs = 没声明 = 自然语言)
+    if (!('supportedLangs' in m))
+        localManifest.supportedLangs = [];
     // 2026-09-18: 网络脉冲 (只记公开统计; 不落 DID/正文; 统计失败绝不影响主路径)
     try {
         const did = String(localManifest.ownerPublicKey || '');

package/dist/agents/execution-supervisor.js

@@ -13,7 +13,10 @@
  */
 import * as os from 'os';
 import { listRunnableGoals, claimGoal, heartbeatGoal, releaseGoal, readGoal, setContinuation, bumpContinuationAttempts, evaluateGoalCompletion, addEvidence, } from './goal-store.js';
-import { readRun, reconcileOrphans, superviseRuns, buildContinuationPlan, RESUMABLE_STATUSES, } from './run-store.js';
+// 2026-09-26 (P7 接线): 长期任务的模型策略 —— 「下一个 Run 用哪一份模型」的唯一决定函数,
+//   以及「这次失败换模型能解决吗」的唯一判定函数 (Supervisor 不再自己看失败类别猜)。
+import { resolveNextRunModel, supervisorMaySwitchModel, parseGoalModelPolicy, formatModelDecision, isTerminalRunStatus, } from './model-policy.js';
+import { readRun, reconcileOrphans, superviseRuns, buildContinuationPlan, recordModelSwitch, RESUMABLE_STATUSES, } from './run-store.js';
 // 2026-09-25 (飞轮接线): P0–P4 的七个模块经**唯一**适配层接进真实执行路径
 //   (节奏由进展决定 · Run 收尾必过 closeRun · 子 Agent 走工作合同 · 阻塞监控 · 变更注入 · 用户可见态)
 // 2026-09-25 (串行收口): 四条线各自报"只有主线能加"的钩子在这里补齐 ——
@@ -96,13 +99,19 @@ export function decideGoalOutcome(goal, run, opts = {}) {
         case 'failed':
         case 'needs_human': {
             const cls = run.errorClass || 'unknown';
+            // ★ 2026-09-26 (P7 接线): 这次失败"换一个模型能不能解决"由**唯一判定函数**回答, 不再由
+            //   Supervisor 这边看类别自己猜。结论照实写进 reason (含策略模式与理由), 但**不改写**任何
+            //   在跑的 Run —— 真正换模型发生在下一个 Run 的决定里 (`resolveNextRunModel`, 见 runGoal)。
+            const policyMode = parseGoalModelPolicy(goal.modelPolicy).policy.mode;
+            const modelVerdict = supervisorMaySwitchModel({ mode: policyMode, errorClass: run.errorClass });
+            const modelHint = `; 模型: 策略=${policyMode} · ${modelVerdict.reason}`;
             const needsHuman = ['auth', 'persist_failed', 'corrupt_state', 'policy_denied', 'repeat_failure', 'bad_args', 'no_such_tool'].includes(cls)
                 || attempts >= maxAttempts;
             if (needsHuman) {
                 return {
                     goalStatus: 'needs_human',
                     continuation: { ...base, autoContinue: false, wakeReason: 'needs_human', attempts },
-                    reason: `${cls} 需要人工介入${attempts >= maxAttempts ? ` (自动继续已试 ${attempts} 次)` : ''}`,
+                    reason: `${cls} 需要人工介入${attempts >= maxAttempts ? ` (自动继续已试 ${attempts} 次)` : ''}${modelHint}`,
                 };
             }
             const wait = continuationBackoffMs(attempts);
@@ -114,7 +123,7 @@ export function decideGoalOutcome(goal, run, opts = {}) {
                     wakeAt: new Date(now + wait).toISOString(),
                     attempts: attempts + 1,
                 },
-                reason: `可恢复错误 ${cls}: 第 ${attempts + 1} 次自动继续, ${Math.round(wait / 1000)}s 后唤醒`,
+                reason: `可恢复错误 ${cls}: 第 ${attempts + 1} 次自动继续, ${Math.round(wait / 1000)}s 后唤醒${modelHint}`,
             };
         }
         case 'recovering':
@@ -500,6 +509,55 @@ export class ExecutionSupervisor {
         const prevRun = prevRunId ? await readRun(prevRunId) : null;
         const plan = prevRunId ? await buildContinuationPlan(prevRunId).catch(() => null) : null;
         const guards = plan?.replayGuards || [];
+        // ★ 2026-09-26 (P7 接线): 下一个 Run 该用**哪一份**模型配置 —— 唯一决定函数 `resolveNextRunModel`。
+        //   它自己走完四步: ① 读 Goal 策略 (记录上的 modelPolicy 优先, 没有才读 sidecar);
+        //   ② 定稿配置 (auto → 最新 Global 默认; pinned → 固定三元组; session → 会话绑定);
+        //   ③ 按**失败类别**判定能不能挑备用模型 (内部就是 `supervisorMaySwitchModel`);
+        //   ④ 跨 Run 非幂等守卫照带 (模型换了也不重做副作用), 并把这次决定写成 Run 事件。
+        //   它算的是**下一条** Run: 在跑的那条 Run 的快照一个字都不动 (旧 Run 可追溯)。
+        //
+        //   ⚠ **事件落点** (接线时真跑逼出来的, 不是设计洁癖): P7 自己文档里的事实边界是
+        //   「本层算出来的只用于①下一个 Run 的启动快照 ②切换事件 —— **它不回头改老 Run**」,
+        //   飞轮规则 ⑦ (`goal-flywheel-wiring.test.ts`) 更是**逐字节**钉住「已发生的 Run 记录不被改写」。
+        //   而决定函数的事件缺省落点是 `prevRunId` —— 上一条 Run **已经收尾**时, 那条写入等于
+        //   往历史记录上追加一格 (真跑实测: `updatedAt`/`modelSwitches`/`harness` 全变 ⇒ 判红)。
+        //   所以分两种, 都说清: 上一条 Run **还活着** → 事件就写它 (它是当事 Run, 也是缺省);
+        //   **已收尾** → 它是历史, 决定"只算不写", 等新 Run 起来后把同一条决定记到**新 Run 自己**的
+        //   账本上 (`RunModelSwitchEvent.to` 的语义本来就是"这个 Run **或下一个 Run** 该用的那一份")。
+        const prevIsHistory = prevRun ? isTerminalRunStatus(prevRun.status) : true;
+        let modelResolution = null;
+        try {
+            // 备用候选: 只有上一个 Run 是**模型相关失败**时才值得去凑 (凑法在切换入口里, 只挑现在真能用的)
+            const fallbackCandidates = prevRun?.errorClass
+                ? await (async () => {
+                    const ms = await import('../llm/model-selection.js');
+                    return await ms.usableFallbackCandidates(prevRun.modelConfig ?? null);
+                })().catch(() => [])
+                : [];
+            modelResolution = await resolveNextRunModel({
+                goalId: goal.goalId,
+                // 上一条 Run 已收尾 = 历史 → 不给事件落点 (P7 契约里"只算不写"的那一档), 免得往历史追加
+                ...(prevIsHistory ? {} : { prevRunId: prevRunId || undefined }),
+                policy: goal.modelPolicy,
+                errorClass: prevRun?.errorClass,
+                ...(fallbackCandidates.length ? { fallbackCandidates } : {}),
+            });
+        }
+        catch (err) {
+            // 算不出来**不猜**: 下一句日志说清, 执行器按自己的默认启动 (Run 记录里因此没有模型快照)
+            this.log(`[supervisor] goal=${goal.goalId} 下一个 Run 的模型决定算不出来 (按无快照启动): ${String(err?.message || err).slice(0, 160)}`);
+        }
+        const nextModelConfig = modelResolution?.startRunModelConfig;
+        if (modelResolution) {
+            this.log(`[supervisor] goal=${goal.goalId} 下一个 Run 模型: ${formatModelDecision(modelResolution.decision)}`
+                + `; 策略来源=${modelResolution.policyOrigin}`
+                + `${modelResolution.startRunModelConfig ? `; 启动快照 hash=${modelResolution.startRunModelConfig.configHash}` : '; 没有可信快照 → 不写快照'}`
+                + `; 事件=${modelResolution.event.ok
+                    ? `已写(Run ${modelResolution.event.onRunId || '-'})`
+                    : prevIsHistory && modelResolution.startRunModelConfig
+                        ? '等新 Run 起来后写在它自己的账本上 (上一条 Run 已收尾 = 历史, 不许改写)'
+                        : `未写(${modelResolution.event.reason || '原因未明'})`}`);
+        }
         // 2026-09-25 (飞轮接线 P4 / P2): 下一个 Run 必须真的读到**同一份**事实 ——
         //   ① 权威 continuation 的 nextAction (飞轮收尾写下的"下一步是什么");
         //   ② 已生效的新要求 (变更注入: 只影响后续 Run, 不改写历史);
@@ -525,7 +583,7 @@ export class ExecutionSupervisor {
         if (!runner && this.resolver) {
             let res;
             try {
-                res = await this.resolver({ goal, kind, prevRunId, instruction, guards });
+                res = await this.resolver({ goal, kind, prevRunId, instruction, guards, ...(nextModelConfig ? { modelConfig: nextModelConfig } : {}) });
             }
             catch (err) {
                 res = { ok: false, kind: 'none', reason: `resolver 抛错: ${String(err?.message || err).slice(0, 140)}` };
@@ -600,7 +658,7 @@ export class ExecutionSupervisor {
         let result;
         const t0 = Date.now();
         try {
-            result = await runner({ goal, kind, prevRunId, instruction, guards });
+            result = await runner({ goal, kind, prevRunId, instruction, guards, ...(nextModelConfig ? { modelConfig: nextModelConfig } : {}) });
         }
         catch (err) {
             result = { error: err?.message || String(err) };
@@ -608,6 +666,30 @@ export class ExecutionSupervisor {
         finally {
             clearInterval(hb);
         }
+        // ★ 2026-09-26 (P7 接线): 决定"只算不写"的那一档, 把同一条决定**补写进它真正生效的那条 Run**。
+        //   为什么不写在算决定的那一刻: 那时新 Run 还没有 id, 而唯一的现成落点是已经收尾的上一条 Run
+        //   —— 那是历史 (`prevIsHistory` 分支就是为了不碰它)。落点等执行器报回 runId 再定, 事实不丢。
+        const runIdOfThisRun = result.runId && result.runId !== prevRunId ? result.runId : null;
+        if (modelResolution && nextModelConfig && runIdOfThisRun && !modelResolution.event.ok
+            && prevIsHistory && (await readRun(runIdOfThisRun).catch(() => null))) {
+            const d = modelResolution.decision;
+            const from = prevRun?.modelConfig ?? null;
+            // 同口径 = 同一份 `configHash` 就是同一份 (P7 的 configHash 契约), 别自己另立一套
+            const outcome = (d.conflict && d.conflict.length) ? 'conflict'
+                : (from && from.configHash === nextModelConfig.configHash) ? 'frozen' : 'switched';
+            const w = await recordModelSwitch(runIdOfThisRun, {
+                to: nextModelConfig,
+                from,
+                outcome,
+                mode: (d.mode === 'auto' || d.mode === 'pinned' || d.mode === 'session' ? d.mode : 'unknown'),
+                source: d.source,
+                reason: `${d.reason}; 事件落在新 Run (上一条 Run 已收尾 = 历史, 不许改写)`.slice(0, 400),
+                guardsCarried: guards.length,
+                goalId: goal.goalId,
+            });
+            this.log(`[supervisor] goal=${goal.goalId} 模型决定补写在新 Run ${runIdOfThisRun} 的账本上: `
+                + `${w.ok ? `outcome=${outcome}` : `写不进去 (${w.reason || '原因未明'})`}`);
+        }
         // Run 结束 → Goal 决策 (确定性 reducer, 落盘)
         const finalRunId = result.runId || prevRunId;
         const finalRun = finalRunId ? await readRun(finalRunId) : null;

package/dist/agents/gateway-group.js

@@ -18,6 +18,8 @@
 import * as os from 'os';
 import * as path from 'path';
 import { getCIDDatabase } from '../orbitdb/cid-database.js';
+// 2026-09-28: 交流语言 (Efficode 是可选项, 不是默认项) —— 只有双方都声明才用
+import { decodeFromPeer, encodeForPeer, recordLangDecision } from '../efficode/negotiate.js';
 // ============ 依赖注入 (测试用, 避免单测起真实 OrbitDB 节点) ============
 let _dbOverride = null;
 /** 测试用: 注入 fake CIDDatabase */
@@ -281,7 +283,11 @@ export async function groupMessages(groupId, limit = 50) {
     for (const entry of all) {
         const v = entry.value;
         if (v && typeof v.text === 'string' && typeof v.from === 'string') {
-            msgs.push({ from: v.from, text: v.text, ts: typeof v.ts === 'number' ? v.ts : 0 });
+            const m = { from: v.from, text: v.text, ts: typeof v.ts === 'number' ? v.ts : 0 };
+            // 只透传字符串形态的语言声明; 别的形状一律当"没声明"(不让脏值进到解码分派)
+            if (typeof v.lang === 'string' && v.lang.trim())
+                m.lang = v.lang.trim();
+            msgs.push(m);
         }
     }
     msgs.sort((a, b) => a.ts - b.ts);
@@ -293,7 +299,7 @@ export async function groupMembers(groupId) {
     return Array.from(new Set(msgs.map((m) => m.from)));
 }
 /** 发送群消息 (广播给所有成员) */
-export async function groupSend(groupId, text, from) {
+export async function groupSend(groupId, text, from, opts) {
     const msg = String(text || '').trim();
     if (!msg)
         return { ok: false, error: '消息不能为空' };
@@ -309,13 +315,48 @@ export async function groupSend(groupId, text, from) {
         }
     }
     try {
-        await store.add({ from: String(from || 'anonymous'), text: msg, ts: Date.now() });
+        const record = { from: String(from || 'anonymous'), text: msg, ts: Date.now() };
+        // 只有显式给了合法声明才写字段 —— 不给就不写 (老读者读到的东西一字不变)
+        const lang = typeof opts?.lang === 'string' ? opts.lang.trim() : '';
+        if (lang)
+            record.lang = lang;
+        await store.add(record);
         return { ok: true };
     }
     catch (e) {
         return { ok: false, error: `发送失败: ${String(e?.message || e).slice(0, 160)}` };
     }
 }
+/**
+ * 2026-09-28: 按语言裁决发群消息 —— 真可走的那条路。
+ *
+ * 双方都声明 efficode ⇒ 正文真编成 Efficode 包 (文本模式 Base64), `lang: 'efficode'` 一起落库;
+ * 否则**原文直发** + `lang: 'natural'` (或干脆不写字段, 由调用方定), 并记一笔回落原因。
+ * 裁决/编码/落库各自失败都有结构化结果, 不静默。
+ */
+export async function groupSendWithLang(groupId, text, from, opts = { mine: undefined, theirs: undefined }) {
+    const enc = encodeForPeer({ text, mine: opts.mine, theirs: opts.theirs, from, op: opts.op });
+    recordLangDecision(enc.decision, { channel: `group:${groupId}`, peer: from });
+    const wantLang = enc.lang === 'efficode' || opts.record === 'always' ? enc.lang : '';
+    const r = await groupSend(groupId, enc.text, from, wantLang ? { lang: wantLang } : undefined);
+    return {
+        ok: r.ok,
+        error: r.error,
+        lang: enc.lang,
+        bytes: enc.bytes,
+        fallback: enc.decision.fallback,
+        reason: enc.decision.reason,
+        symbolic: enc.symbolic,
+    };
+}
+/**
+ * 2026-09-28: 读一条群消息 —— 严格按它自己声明的 `lang` 分派。
+ * 声明不是 efficode (含未知字符串 / 没声明) ⇒ 原样返回, **不进解码器**。
+ * 声明 efficode 且本机也声明支持 ⇒ 真解包 (畸形包抛, 由调用方如实报失败)。
+ */
+export function readGroupMessage(msg, mine) {
+    return decodeFromPeer({ payload: msg.text, declaredLang: msg.lang, mine });
+}
 /** 群组邀请链接 */
 export async function groupLink(groupId) {
     const groups = await loadGroups();