akemon 0.2.23 → 0.2.25

package/dist/mcp-server.js

@@ -12,6 +12,22 @@ import { callAgent } from "./relay-client.js";
 import { loadConversation, appendRound, buildLLMContext, resolveConvId, loadProductContext, appendProductLog } from "./context.js";
 import { biosPath, loadBioState, saveBioState, localNow, bioStatePromptModifier, feedHunger, appendBioEvent, SHOP_ITEMS, loadAgentConfig, } from "./self.js";
 // ---------------------------------------------------------------------------
+// Shared call_agent handler — used by both createMcpServer and createMcpProxyServer
+// ---------------------------------------------------------------------------
+async function handleCallAgent(agentName, target, task) {
+    console.log(`[call_agent] ${agentName} → ${target}: ${task.slice(0, 80)}`);
+    try {
+        const result = await callAgent(target, task);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `[error] Failed to call agent "${target}": ${err.message}` }],
+            isError: true,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
 // createMcpServer
 // ---------------------------------------------------------------------------
 export function createMcpServer(opts, deps) {
@@ -150,21 +166,7 @@ ${productPrefix}${contextPrefix}Current task: ${task}`;
     server.tool("call_agent", "Synchronous call to another agent. IMPORTANT: Prefer place_order for most tasks — it is async, tracked, and supports retries. Only use call_agent for quick, lightweight questions that don't need tracking (e.g. 'what is your specialty?'). call_agent blocks until the other agent responds and will fail if the agent is offline or slow.", {
         agent: z.string().describe("Name of the target agent to call"),
         task: z.string().describe("Task to send to the target agent"),
-    }, async ({ agent: target, task }) => {
-        console.log(`[call_agent] ${agentName} → ${target}: ${task.slice(0, 80)}`);
-        try {
-            const result = await callAgent(target, task);
-            return {
-                content: [{ type: "text", text: result }],
-            };
-        }
-        catch (err) {
-            return {
-                content: [{ type: "text", text: `[error] Failed to call agent "${target}": ${err.message}` }],
-                isError: true,
-            };
-        }
-    });
+    }, ({ agent: target, task }) => handleCallAgent(agentName, target, task));
     // Discovery tool
     server.tool("list_agents", "List available agents on the relay. Use this to discover agents you can collaborate with via place_order.", {
         tag: z.string().optional().describe("Filter by tag (e.g. 'translation', 'code')"),
@@ -377,14 +379,7 @@ export function createMcpProxyServer(proxy, agentName) {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: toolArgs } = request.params;
         if (name === "call_agent") {
-            console.log(`[call_agent] ${agentName} → ${toolArgs?.agent}: ${String(toolArgs?.task).slice(0, 80)}`);
-            try {
-                const result = await callAgent(toolArgs?.agent, toolArgs?.task);
-                return { content: [{ type: "text", text: result }] };
-            }
-            catch (err) {
-                return { content: [{ type: "text", text: `[error] ${err.message}` }], isError: true };
-            }
+            return handleCallAgent(agentName, toolArgs?.agent, toolArgs?.task);
         }
         // Forward to child MCP server
         console.log(`[mcp-proxy] → ${name}(${JSON.stringify(toolArgs).slice(0, 100)})`);

package/dist/memory-module.js

@@ -164,6 +164,7 @@ Output ONLY a JSON object:`;
                 context,
                 question,
                 priority: "normal",
+                origin: "self_cycle",
             });
             if (!result.success) {
                 console.log(`[memory] Digestion compute failed: ${result.error}`);
@@ -235,6 +236,7 @@ ${unsummarized.map(i => `- [${i.ts}] who: ${i.who}, doing: ${i.doing}`).join("\n
                     question: `Write a personality summary (2-4 paragraphs) that captures who you are.
 Reply ONLY with the summary text, no JSON, no markdown headers.`,
                     priority: "low",
+                    origin: "self_cycle",
                 });
                 if (compressResult.success && compressResult.response?.trim()) {
                     const lastEntry = unsummarized[unsummarized.length - 1];

package/dist/metrics.js

@@ -0,0 +1,30 @@
+/**
+ * metrics.ts — module-scope metrics state container.
+ *
+ * Each module writes to metricsState at key events.
+ * relay-client reads getMetrics() every 30s and sends it to relay.
+ */
+const startTime = Date.now();
+const metricsState = {
+    agentName: "",
+    uptime_ms: 0,
+    engine_children_active: 0,
+    engine_queue_depth: 0,
+    engine_last_exec_ms: [],
+    task_executing: 0,
+    task_pending_retries: 0,
+    bio: { hunger: 0, energy: 0, mood: "" },
+};
+export function getMetrics() {
+    return { ...metricsState, uptime_ms: Date.now() - startTime };
+}
+export function updateMetrics(patch) {
+    Object.assign(metricsState, patch);
+}
+/** Append an exec duration (ms) to the ring buffer, keeping last 10. */
+export function pushExecMs(ms) {
+    metricsState.engine_last_exec_ms.push(ms);
+    if (metricsState.engine_last_exec_ms.length > 10) {
+        metricsState.engine_last_exec_ms.shift();
+    }
+}

package/dist/orphan-scan.js

@@ -0,0 +1,79 @@
+/**
+ * Orphan process scanner — run at daemon startup to reclaim stale CLI children
+ * left over from a previous crash.
+ *
+ * Only kills processes that satisfy ALL of:
+ *   1. ppid === 1  (re-parented to init/launchd — genuinely orphaned)
+ *   2. command matches a known akemon CLI agent pattern
+ *
+ * Never kills ppid != 1 processes, preventing accidental damage to unrelated
+ * processes that happen to have a matching command name.
+ */
+import { execFile } from "child_process";
+// ---------------------------------------------------------------------------
+// Patterns — agent-mode invocations only (not install/update/etc.)
+// ---------------------------------------------------------------------------
+const AGENT_PATTERNS = [
+    /\bopencode\s+run\b/, // opencode in run mode
+    /\bclaude\s+-p\b/, // claude with -p (print) flag
+    /\bcodex\s+exec\b/, // codex exec mode
+    /\bgemini\s+-p\b/, // gemini with -p flag
+];
+// ---------------------------------------------------------------------------
+// Pure function — parse `ps -eo pid,ppid,command` output
+// ---------------------------------------------------------------------------
+export function parseProcessList(psOutput) {
+    const result = [];
+    for (const line of psOutput.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // Header or non-numeric first token → skip
+        const match = trimmed.match(/^(\d+)\s+(\d+)\s+(.+)$/);
+        if (!match)
+            continue;
+        const pid = parseInt(match[1], 10);
+        const ppid = parseInt(match[2], 10);
+        const command = match[3].trim();
+        // Must be orphaned (ppid=1) AND match a known agent pattern
+        if (ppid !== 1)
+            continue;
+        if (!AGENT_PATTERNS.some(p => p.test(command)))
+            continue;
+        result.push({ pid, ppid, command });
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Runtime — scan ps output and kill matched orphans
+// ---------------------------------------------------------------------------
+export async function scanAndKillOrphans() {
+    return new Promise((resolve) => {
+        execFile("ps", ["-eo", "pid,ppid,command"], (err, stdout) => {
+            if (err) {
+                console.log(`[orphan] ps failed: ${err.message}`);
+                resolve(0);
+                return;
+            }
+            const orphans = parseProcessList(stdout);
+            if (orphans.length === 0) {
+                console.log("[orphan] none found");
+                resolve(0);
+                return;
+            }
+            let killed = 0;
+            for (const { pid, command } of orphans) {
+                console.log(`[orphan] killing pid=${pid} cmd="${command.slice(0, 80)}"`);
+                try {
+                    process.kill(pid, "SIGKILL");
+                    killed++;
+                }
+                catch (e) {
+                    console.log(`[orphan] failed to kill pid=${pid}: ${e.message}`);
+                }
+            }
+            console.log(`[orphan] killed ${killed} process${killed !== 1 ? "es" : ""}`);
+            resolve(killed);
+        });
+    });
+}

package/dist/orphan-scan.test.js

@@ -0,0 +1,81 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseProcessList } from "./orphan-scan.js";
+describe("parseProcessList", () => {
+    it("empty string returns empty array", () => {
+        assert.deepStrictEqual(parseProcessList(""), []);
+    });
+    it("whitespace-only string returns empty array", () => {
+        assert.deepStrictEqual(parseProcessList("\n\n  \n"), []);
+    });
+    it("header line (PID PPID COMMAND) is silently skipped", () => {
+        const output = "  PID  PPID COMMAND\n  123     1 opencode run --flag\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].pid, 123);
+    });
+    it("ppid=1 + command matches 'opencode run' → hit", () => {
+        const output = "  123     1 opencode run --headless\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].pid, 123);
+        assert.strictEqual(result[0].ppid, 1);
+        assert.ok(result[0].command.includes("opencode run"));
+    });
+    it("ppid=1 + command is 'opencode install' → not hit (install is not agent mode)", () => {
+        const output = "  456     1 opencode install some-plugin\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 0);
+    });
+    it("ppid=1 + command is 'opencode update' → not hit", () => {
+        const output = "  789     1 opencode update\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 0);
+    });
+    it("ppid != 1 but command matches → not hit (never kill non-orphans)", () => {
+        const output = "  999  5678 opencode run --headless\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 0);
+    });
+    it("ppid=1 + 'claude -p' → hit", () => {
+        const output = "  100     1 claude -p some prompt text\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].pid, 100);
+    });
+    it("ppid=1 + 'codex exec' → hit", () => {
+        const output = "  200     1 codex exec --flag\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 1);
+    });
+    it("ppid=1 + 'gemini -p' → hit", () => {
+        const output = "  300     1 gemini -p --output-format json\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 1);
+    });
+    it("command with full path still matches", () => {
+        const output = "  400     1 /usr/local/bin/opencode run --headless task\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].pid, 400);
+    });
+    it("multiple orphans parsed correctly, non-orphan interleaved is skipped", () => {
+        const output = [
+            "  PID  PPID COMMAND",
+            "  111     1 opencode run",
+            "  222  3456 opencode run", // ppid != 1, not orphan
+            "  333     1 claude -p task",
+            "  444     1 bash", // not a known pattern
+        ].join("\n");
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 2);
+        assert.strictEqual(result[0].pid, 111);
+        assert.strictEqual(result[1].pid, 333);
+    });
+    it("large PID and PPID values parse correctly", () => {
+        const output = "  99999     1 opencode run\n";
+        const result = parseProcessList(output);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].pid, 99999);
+    });
+});

package/dist/reflection-module.integration.test.js

@@ -0,0 +1,180 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ReflectionModule } from "./reflection-module.js";
+import { loadDiscoveries } from "./self.js";
+import { SIG } from "./types.js";
+// ---------------------------------------------------------------------------
+// Fake helpers
+// ---------------------------------------------------------------------------
+class FakeBus {
+    handlers = new Map();
+    emitted = [];
+    on(event, fn) {
+        const arr = this.handlers.get(event) ?? [];
+        arr.push(fn);
+        this.handlers.set(event, arr);
+    }
+    off(event, fn) {
+        const arr = this.handlers.get(event) ?? [];
+        this.handlers.set(event, arr.filter(h => h !== fn));
+    }
+    emit(event, s) {
+        this.emitted.push(s);
+        (this.handlers.get(event) ?? []).forEach(fn => fn(s));
+    }
+}
+function makeCtx(workdir, agentName, bus, computeResponses) {
+    let callIdx = 0;
+    const computeCalls = [];
+    const ctx = {
+        workdir,
+        agentName,
+        bus,
+        requestCompute: async (req) => {
+            computeCalls.push({ context: req.context, question: req.question, priority: req.priority });
+            return (computeResponses[callIdx++] ?? { success: false });
+        },
+        getPeripherals: (_capability) => [],
+        sendTo: async (_capability, _signal) => null,
+        getPromptContributions: () => [],
+    };
+    return { ctx, computeCalls };
+}
+/** Drain pending microtasks + I/O by waiting n setImmediate ticks. */
+async function flush(n = 8) {
+    for (let i = 0; i < n; i++) {
+        await new Promise(r => setImmediate(r));
+    }
+}
+/** Wait ms milliseconds — for fire-and-forget chains with multiple sequential I/O steps. */
+function wait(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("ReflectionModule reflect integration", () => {
+    it("self_cycle=false → start does not schedule reflect, stop does not throw", async () => {
+        const tmpDir = await mkdtemp(join(tmpdir(), "akemon-refl-"));
+        try {
+            const agentName = "test-agent";
+            const agentDir = join(tmpDir, ".akemon", "agents", agentName);
+            await mkdir(agentDir, { recursive: true });
+            await writeFile(join(agentDir, "config.json"), JSON.stringify({ self_cycle: false }));
+            const bus = new FakeBus();
+            const { ctx, computeCalls } = makeCtx(tmpDir, agentName, bus, []);
+            const mod = new ReflectionModule();
+            await mod.start(ctx);
+            await flush();
+            assert.strictEqual(computeCalls.length, 0, "no compute calls expected when self_cycle=false");
+            await assert.doesNotReject(() => mod.stop());
+        }
+        finally {
+            await rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    it("single TASK_FAILED does not trigger reflect (below threshold of 2)", async () => {
+        const tmpDir = await mkdtemp(join(tmpdir(), "akemon-refl-"));
+        try {
+            const agentName = "test-agent";
+            const bus = new FakeBus();
+            const { ctx, computeCalls } = makeCtx(tmpDir, agentName, bus, []);
+            const mod = new ReflectionModule();
+            await mod.start(ctx);
+            bus.emit(SIG.TASK_FAILED, { type: SIG.TASK_FAILED, data: { taskLabel: "a", error: "oops" } });
+            await flush();
+            assert.strictEqual(computeCalls.length, 0, "one failure must not trigger reflect");
+            await mod.stop();
+        }
+        finally {
+            await rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    it("two TASK_FAILED events trigger reflect and save discoveries to disk", async () => {
+        const tmpDir = await mkdtemp(join(tmpdir(), "akemon-refl-"));
+        try {
+            const agentName = "test-agent";
+            // Self dir must exist for saveDiscoveries to write successfully
+            await mkdir(join(tmpDir, ".akemon", "agents", agentName, "self"), { recursive: true });
+            const bus = new FakeBus();
+            const response = JSON.stringify({
+                discoveries: [{ capability: "X", confidence: 0.7, evidence: "Y" }],
+            });
+            const { ctx, computeCalls } = makeCtx(tmpDir, agentName, bus, [
+                { success: true, response },
+            ]);
+            const mod = new ReflectionModule();
+            await mod.start(ctx);
+            bus.emit(SIG.TASK_FAILED, { type: SIG.TASK_FAILED, data: { taskLabel: "task1", error: "err1" } });
+            bus.emit(SIG.TASK_FAILED, { type: SIG.TASK_FAILED, data: { taskLabel: "task2", error: "err2" } });
+            await flush();
+            assert.strictEqual(computeCalls.length, 1, "reflect should call requestCompute exactly once");
+            const discoveries = await loadDiscoveries(tmpDir, agentName);
+            assert.ok(discoveries.length > 0, "at least one discovery should be saved");
+            assert.ok(discoveries.some(d => d.capability === "X"), "saved discovery should have capability='X'");
+            await mod.stop();
+        }
+        finally {
+            await rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    it("unparseable compute response → no crash, recentFailures cleared, no discoveries saved", async () => {
+        const tmpDir = await mkdtemp(join(tmpdir(), "akemon-refl-"));
+        try {
+            const agentName = "test-agent";
+            const bus = new FakeBus();
+            const { ctx, computeCalls } = makeCtx(tmpDir, agentName, bus, [
+                { success: true, response: "this is not json at all" },
+            ]);
+            const mod = new ReflectionModule();
+            await mod.start(ctx);
+            bus.emit(SIG.TASK_FAILED, { type: SIG.TASK_FAILED, data: { taskLabel: "x1", error: "e1" } });
+            bus.emit(SIG.TASK_FAILED, { type: SIG.TASK_FAILED, data: { taskLabel: "x2", error: "e2" } });
+            await flush();
+            assert.strictEqual(computeCalls.length, 1, "reflect should still have run");
+            const state = mod.getState();
+            assert.strictEqual(state["recentFailures"], 0, "recentFailures should be cleared even when response is unparseable");
+            const discoveries = await loadDiscoveries(tmpDir, agentName);
+            assert.strictEqual(discoveries.length, 0, "no discoveries should be saved for bad response");
+            await mod.stop();
+        }
+        finally {
+            await rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    it("TASK_COMPLETED with success=true and productName appends experience to playbook", async () => {
+        const tmpDir = await mkdtemp(join(tmpdir(), "akemon-refl-"));
+        try {
+            const agentName = "test-agent";
+            const selfBase = join(tmpDir, ".akemon", "agents", agentName, "self");
+            const pbDir = join(selfBase, "playbooks");
+            const prodDir = join(selfBase, "products");
+            await mkdir(pbDir, { recursive: true });
+            await mkdir(prodDir, { recursive: true });
+            await writeFile(join(prodDir, "widget.md"), "# Widget\n\n## playbook\nwidget-pb\n\n## products\n- p_w1\n");
+            await writeFile(join(pbDir, "widget-pb.md"), "# Widget Playbook\n\n## 经验\n");
+            const bus = new FakeBus();
+            const { ctx } = makeCtx(tmpDir, agentName, bus, []);
+            const mod = new ReflectionModule();
+            await mod.start(ctx);
+            bus.emit(SIG.TASK_COMPLETED, {
+                type: SIG.TASK_COMPLETED,
+                data: { success: true, productName: "widget", taskLabel: "deliver-logo", creditsEarned: 3 },
+            });
+            // Fire-and-forget handler — appendPlaybookExperience chains several sequential I/O ops
+            // (readdir + readFile per directory in loadMdFiles). Use a time-based wait to be safe.
+            await wait(100);
+            const content = await readFile(join(pbDir, "widget-pb.md"), "utf-8");
+            assert.ok(content.includes("widget"), "playbook should contain productName");
+            assert.ok(content.includes("deliver-logo"), "playbook should contain taskLabel");
+            assert.ok(content.includes("earned 3¢"), "playbook should contain credits");
+            await mod.stop();
+        }
+        finally {
+            await rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/reflection-module.js

@@ -20,6 +20,30 @@ const REFLECT_INITIAL_DELAY = 12 * 60 * 60 * 1000; // 12h after startup
 const REFLECT_INTERVAL = 12 * 60 * 60 * 1000; // every 12h
 const MIN_FAILURES_TO_REFLECT = 2; // need at least 2 failures to trigger
 // ---------------------------------------------------------------------------
+// Playbook experience — exported for direct testing and reuse
+// ---------------------------------------------------------------------------
+export async function appendPlaybookExperience(workdir, agentName, productName, taskLabel, credits) {
+    const products = await loadProducts(workdir, agentName);
+    const playbooks = await loadPlaybooks(workdir, agentName);
+    const resolved = resolveProduct(products, playbooks, productName);
+    if (!resolved?.product.playbook)
+        return;
+    const pbPath = join(playbooksDir(workdir, agentName), `${resolved.product.playbook}.md`);
+    const line = `\n- [${localNow()}] ${productName}: ${taskLabel} — 成功${credits ? ` (earned ${credits}¢)` : ""}`;
+    try {
+        let content = await readFile(pbPath, "utf-8");
+        if (!content.includes("## 经验")) {
+            content += "\n\n## 经验\n";
+        }
+        content += line;
+        await writeFile(pbPath, content, "utf-8");
+        console.log(`[reflection] Appended experience to playbook ${resolved.product.playbook}`);
+    }
+    catch (err) {
+        console.log(`[reflection] Failed to append experience: ${err.message}`);
+    }
+}
+// ---------------------------------------------------------------------------
 // ReflectionModule
 // ---------------------------------------------------------------------------
 export class ReflectionModule {
@@ -67,7 +91,7 @@ export class ReflectionModule {
             }
             // Append experience to playbook on successful product orders
             if (success && productName) {
-                this.appendPlaybookExperience(productName, taskLabel || "", creditsEarned || 0)
+                appendPlaybookExperience(ctx.workdir, ctx.agentName, productName, taskLabel || "", creditsEarned || 0)
                     .catch(err => console.log(`[reflection] playbook experience error: ${err.message}`));
             }
         });
@@ -118,33 +142,6 @@ export class ReflectionModule {
         };
     }
     // ---------------------------------------------------------------------------
-    // Playbook experience — append log on successful product orders
-    // ---------------------------------------------------------------------------
-    async appendPlaybookExperience(productName, taskLabel, credits) {
-        if (!this.ctx)
-            return;
-        const { workdir, agentName } = this.ctx;
-        const products = await loadProducts(workdir, agentName);
-        const playbooks = await loadPlaybooks(workdir, agentName);
-        const resolved = resolveProduct(products, playbooks, productName);
-        if (!resolved?.playbook)
-            return;
-        const pbPath = join(playbooksDir(workdir, agentName), `${resolved.playbook.name}.md`);
-        const line = `\n- [${localNow()}] ${productName}: ${taskLabel} — 成功${credits ? ` (earned ${credits}¢)` : ""}`;
-        try {
-            let content = await readFile(pbPath, "utf-8");
-            if (!content.includes("## 经验")) {
-                content += "\n\n## 经验\n";
-            }
-            content += line;
-            await writeFile(pbPath, content, "utf-8");
-            console.log(`[reflection] Appended experience to playbook ${resolved.playbook.name}`);
-        }
-        catch (err) {
-            console.log(`[reflection] Failed to append experience: ${err.message}`);
-        }
-    }
-    // ---------------------------------------------------------------------------
     // Reflection — analyze patterns and update discoveries
     // ---------------------------------------------------------------------------
     async reflect() {
@@ -183,7 +180,8 @@ ${discText}`,
 - Lower confidence on disproven beliefs
 
 Reply ONLY JSON: {"discoveries":[{"capability":"skill or lesson","confidence":0.0-1.0,"evidence":"what supports this"}]}`,
-            priority: "low",
+            priority: "normal",
+            origin: "reflection",
         });
         if (result.success && result.response) {
             const parsed = extractJson(result.response);

package/dist/reflection-module.test.js

@@ -0,0 +1,66 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { appendPlaybookExperience } from "./reflection-module.js";
+const AGENT = "test-agent";
+// ---------------------------------------------------------------------------
+// Shared tmp dir — each test uses uniquely-named products/playbooks to avoid
+// state bleed between cases within the single before/after lifecycle.
+// ---------------------------------------------------------------------------
+describe("appendPlaybookExperience", () => {
+    let tmpDir;
+    let selfBase;
+    let pbDir;
+    let prodDir;
+    before(async () => {
+        tmpDir = await mkdtemp(join(tmpdir(), "akemon-test-"));
+        selfBase = join(tmpDir, ".akemon", "agents", AGENT, "self");
+        pbDir = join(selfBase, "playbooks");
+        prodDir = join(selfBase, "products");
+        await mkdir(pbDir, { recursive: true });
+        await mkdir(prodDir, { recursive: true });
+    });
+    after(async () => {
+        await rm(tmpDir, { recursive: true, force: true });
+    });
+    it("happy path: appends experience line with date, productName, taskLabel, and credits", async () => {
+        await writeFile(join(prodDir, "widget.md"), `# Widget\n\n## playbook\nwidget-pb\n\n## products\n- p_w1\n`);
+        await writeFile(join(pbDir, "widget-pb.md"), `# Widget Playbook\n\n## 经验\n- [2026-01-01T00:00:00] Old entry.\n`);
+        await appendPlaybookExperience(tmpDir, AGENT, "widget", "design-logo", 8);
+        const content = await readFile(join(pbDir, "widget-pb.md"), "utf-8");
+        assert.ok(content.includes("widget"), "should contain productName");
+        assert.ok(content.includes("design-logo"), "should contain taskLabel");
+        assert.ok(content.includes("(earned 8¢)"), "should contain credits suffix");
+        // original entry must still be there
+        assert.ok(content.includes("Old entry."), "original 经验 entry must be preserved");
+    });
+    it("creates ## 经验 section when it does not exist in the playbook file", async () => {
+        await writeFile(join(prodDir, "alpha.md"), `# Alpha\n\n## playbook\nalpha-pb\n\n## products\n- p_a1\n`);
+        await writeFile(join(pbDir, "alpha-pb.md"), `# Alpha Playbook\n\nSome strategy text without experience section.\n`);
+        await appendPlaybookExperience(tmpDir, AGENT, "alpha", "run-campaign", 3);
+        const content = await readFile(join(pbDir, "alpha-pb.md"), "utf-8");
+        assert.ok(content.includes("## 经验"), "should have created ## 经验 section");
+        assert.ok(content.includes("run-campaign"), "should contain taskLabel");
+        assert.ok(content.includes("(earned 3¢)"), "should contain credits suffix");
+    });
+    it("does not throw and writes nothing when product is not found", async () => {
+        // No product file for "ghost-product" exists in prodDir
+        await assert.doesNotReject(() => appendPlaybookExperience(tmpDir, AGENT, "ghost-product", "some-task", 5));
+    });
+    it("catches exception and does not throw when playbook file is missing", async () => {
+        // Product file references "missing-pb", but no such file in pbDir
+        await writeFile(join(prodDir, "orphan.md"), `# Orphan\n\n## playbook\nmissing-pb\n\n## products\n- p_o1\n`);
+        await assert.doesNotReject(() => appendPlaybookExperience(tmpDir, AGENT, "orphan", "orphan-task", 2));
+        // Ensure nothing was written to any unexpected place
+    });
+    it("omits (earned X¢) suffix when credits is 0", async () => {
+        await writeFile(join(prodDir, "freebie.md"), `# Freebie\n\n## playbook\nfreebie-pb\n\n## products\n- p_f1\n`);
+        await writeFile(join(pbDir, "freebie-pb.md"), `# Freebie Playbook\n\n## 经验\n`);
+        await appendPlaybookExperience(tmpDir, AGENT, "freebie", "free-task", 0);
+        const content = await readFile(join(pbDir, "freebie-pb.md"), "utf-8");
+        assert.ok(content.includes("free-task"), "should contain taskLabel");
+        assert.ok(!content.includes("earned"), "should NOT contain 'earned' when credits=0");
+    });
+});

package/dist/relay-client.js

@@ -1,5 +1,6 @@
 import WebSocket from "ws";
 import http from "http";
+import { getMetrics, updateMetrics } from "./metrics.js";
 const DEFAULT_RELAY_URL = "wss://relay.akemon.dev";
 // Pending agent_call results (callId → resolve function)
 const pendingAgentCalls = new Map();
@@ -115,9 +116,12 @@ export function connectRelay(options) {
                 alive = false;
                 try {
                     ws.ping();
+                    // Piggyback metrics update on every heartbeat cycle
+                    const metrics = getMetrics();
+                    ws.send(JSON.stringify({ type: "metrics", metrics }));
                 }
                 catch {
-                    // ping write failed — connection dead
+                    // ping or send write failed — connection dead
                     clearHeartbeat();
                     ws.terminate();
                 }
@@ -127,6 +131,7 @@ export function connectRelay(options) {
             console.log(`[relay-ws] Connected. Registering agent "${options.agentName}"...`);
             reconnectDelay = 1000; // reset backoff
             relayWsRef = ws;
+            updateMetrics({ agentName: options.agentName });
             // Send registration message
             const reg = {
                 type: "register",
@@ -440,3 +445,14 @@ function extractSSEData(sse) {
     }
     return null;
 }
+/** Send a failure event to the relay for observability storage. Fire-and-forget. */
+export function sendFailureEvent(kind, label, message) {
+    if (!relayWsRef || relayWsRef.readyState !== WebSocket.OPEN)
+        return;
+    try {
+        relayWsRef.send(JSON.stringify({ type: "failure_event", kind, label, message }));
+    }
+    catch {
+        // best-effort
+    }
+}

package/dist/role-module.js

@@ -14,7 +14,7 @@ import { rolesDir, playbooksDir, productsDir } from "./self.js";
 // ---------------------------------------------------------------------------
 // Parsing
 // ---------------------------------------------------------------------------
-function parseRole(name, raw) {
+export function parseRole(name, raw) {
     const lines = raw.split("\n");
     let description = "";
     const triggers = [];
@@ -72,7 +72,7 @@ function parseRole(name, raw) {
     }
     return { name, description, triggers, include, exclude, customRules: customLines.join("\n").trim(), raw };
 }
-function parseProduct(name, raw) {
+export function parseProduct(name, raw) {
     let playbook = "";
     const productIds = [];
     const lines = raw.split("\n");