@mclawnet/swarm 0.1.4 → 0.1.5

package/dist/__tests__/inbox-persistence-recovery.test.js

@@ -0,0 +1,139 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+vi.mock("@mclawnet/logger", () => ({
+    createLogger: () => ({
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+    }),
+}));
+import { InboxStore } from "../inbox-store.js";
+import { InboxRelay } from "../inbox-relay.js";
+function createMockSessionAdapter() {
+    const inputs = [];
+    const adapter = {
+        _inputs: inputs,
+        createSession: vi.fn(async (options) => `proc-${options.sessionId}`),
+        sendInput: vi.fn((sessionId, input) => {
+            inputs.push({ sessionId, input });
+        }),
+        closeSession: vi.fn(async () => { }),
+    };
+    return adapter;
+}
+function makeFakeSwarm(swarmId, workDir, instanceId) {
+    const role = {
+        instanceId,
+        roleName: "queen",
+        definition: {},
+        roleSessionId: `proc-${swarmId}::${instanceId}`,
+        status: "active",
+    };
+    const roles = new Map();
+    roles.set(instanceId, role);
+    return {
+        id: swarmId,
+        hubSessionId: swarmId,
+        workDir,
+        roles,
+        plan: null,
+        nextInstanceSeq: new Map(),
+        idleCheckCount: 0,
+        maxIdleChecks: 10,
+        isPaused: false,
+        status: "running",
+        planStatus: "none",
+    };
+}
+const baseMsg = {
+    from: "queen",
+    type: "task",
+    data: "do work",
+    timestamp: 1,
+    delivered: false,
+};
+let HOME;
+let WORK;
+beforeEach(() => {
+    HOME = mkdtempSync(join(tmpdir(), "swarm-recovery-"));
+    WORK = mkdtempSync(join(tmpdir(), "swarm-recovery-work-"));
+    process.env.CLAWNET_HOME = HOME;
+});
+afterEach(() => {
+    rmSync(HOME, { recursive: true, force: true });
+    rmSync(WORK, { recursive: true, force: true });
+    delete process.env.CLAWNET_HOME;
+});
+describe("Cross-process inbox persistence recovery", () => {
+    it("append + markDelivered are visible across new InboxStore instances", async () => {
+        const swarmId = "sw-recover-1";
+        const instanceId = "queen-0";
+        // Instance A: write + mark delivered
+        const storeA = new InboxStore(WORK, swarmId);
+        await storeA.append(instanceId, { ...baseMsg, id: "m1", data: "task A" });
+        await storeA.append(instanceId, { ...baseMsg, id: "m2", data: "task B" });
+        await storeA.markDelivered(instanceId, ["m1", "m2"]);
+        // Drop A entirely; create new instance B against same workDir/swarmId
+        const storeB = new InboxStore(WORK, swarmId);
+        const all = await storeB.readAll(instanceId);
+        expect(all.length).toBe(2);
+        expect(all.every((m) => m.delivered === true)).toBe(true);
+        expect(all.every((m) => typeof m.deliveredAt === "number")).toBe(true);
+        const undelivered = await storeB.readUndelivered(instanceId);
+        expect(undelivered.length).toBe(0);
+    });
+    it("messages appended without markDelivered remain undelivered after restart", async () => {
+        const swarmId = "sw-recover-2";
+        const instanceId = "queen-0";
+        // Instance A: only append, simulate agent crash before turn-settled
+        const storeA = new InboxStore(WORK, swarmId);
+        await storeA.append(instanceId, { ...baseMsg, id: "m-crash", data: "never acked" });
+        // Drop A; new instance B
+        const storeB = new InboxStore(WORK, swarmId);
+        const undelivered = await storeB.readUndelivered(instanceId);
+        expect(undelivered.length).toBe(1);
+        expect(undelivered[0].id).toBe("m-crash");
+        expect(undelivered[0].delivered).toBe(false);
+    });
+    it("InboxRelay rebuilt after restart does not re-push already-delivered messages", async () => {
+        const swarmId = "sw-recover-3";
+        const instanceId = "queen-0";
+        const sessionAdapter = createMockSessionAdapter();
+        const swarm = makeFakeSwarm(swarmId, WORK, instanceId);
+        const getSwarm = (id) => (id === swarmId ? swarm : undefined);
+        // Pre-populate inbox with one message via an independent store instance
+        const storeA = new InboxStore(WORK, swarmId);
+        await storeA.append(instanceId, { ...baseMsg, id: "persist-1", data: "first delivery" });
+        // InboxRelay instance 1: deliver → sendInput pushes once
+        const relay1 = new InboxRelay(sessionAdapter, getSwarm);
+        await relay1.deliver(swarmId, instanceId);
+        const pushes1 = sessionAdapter._inputs.filter((i) => i.input.includes("<info_for_agent>"));
+        expect(pushes1.length).toBe(1);
+        expect(pushes1[0].input).toContain('id="persist-1"');
+        // Settle the turn — this calls markDelivered(persist-1) on the on-disk inbox
+        await relay1.onAgentTurnSettled(swarmId, instanceId);
+        // Sanity: the message is now delivered=true on disk
+        const verifyStore = new InboxStore(WORK, swarmId);
+        const after = await verifyStore.readAll(instanceId);
+        expect(after.find((m) => m.id === "persist-1")?.delivered).toBe(true);
+        // Drop relay1 + storeA — simulate process restart
+        // Construct a fresh InboxRelay instance 2 (fresh inFlight + pendingEchoes maps)
+        const relay2 = new InboxRelay(sessionAdapter, getSwarm);
+        const beforeReplay = sessionAdapter._inputs.length;
+        await relay2.deliver(swarmId, instanceId);
+        const afterReplay = sessionAdapter._inputs.length;
+        // Should NOT push persist-1 again, since the on-disk inbox shows it delivered
+        expect(afterReplay).toBe(beforeReplay);
+        // Append a brand new message — relay2 SHOULD push only that one
+        await verifyStore.append(instanceId, { ...baseMsg, id: "persist-2", data: "second delivery" });
+        await relay2.deliver(swarmId, instanceId);
+        const pushes2 = sessionAdapter._inputs.filter((i) => i.input.includes("<info_for_agent>"));
+        expect(pushes2.length).toBe(2);
+        expect(pushes2[1].input).toContain('id="persist-2"');
+        expect(pushes2[1].input).not.toContain('id="persist-1"');
+    });
+});
+//# sourceMappingURL=inbox-persistence-recovery.test.js.map

package/dist/__tests__/inbox-persistence-recovery.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-persistence-recovery.test.js","sourceRoot":"","sources":["../../src/__tests__/inbox-persistence-recovery.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/inbox-relay-interceptor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=inbox-relay-interceptor.test.d.ts.map

package/dist/__tests__/inbox-relay-interceptor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-relay-interceptor.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/inbox-relay-interceptor.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/inbox-relay-interceptor.test.js

@@ -0,0 +1,156 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { InboxRelay } from "../inbox-relay.js";
+import { InboxStore } from "../inbox-store.js";
+const adapter = () => ({
+    createSession: vi.fn(async () => ""),
+    sendInput: vi.fn(),
+    closeSession: vi.fn(async () => { }),
+});
+const fakeSwarm = (workDir = "/tmp/relayInterceptProj", swarmId = "sw1") => ({
+    id: swarmId,
+    hubSessionId: swarmId,
+    workDir,
+    roles: new Map(),
+    plan: null,
+    nextInstanceSeq: new Map(),
+    idleCheckCount: 0,
+    maxIdleChecks: 10,
+    isPaused: false,
+    status: "running",
+    planStatus: "none",
+});
+const fakeRole = (instanceId, status = "active") => ({
+    instanceId,
+    roleName: "queen",
+    definition: {
+        name: "queen",
+        shortName: "queen",
+        type: "queen",
+        description: "",
+        capabilities: [],
+        color: "yellow",
+        promptBody: "",
+    },
+    roleSessionId: `swsess::${instanceId}`,
+    status,
+});
+const baseMsg = {
+    from: "reviewer-0",
+    type: "plan_review_result",
+    data: JSON.stringify({ verdict: "approved", body: "" }),
+    timestamp: 1,
+    delivered: false,
+};
+let HOME;
+beforeEach(() => {
+    HOME = mkdtempSync(join(tmpdir(), "relay-intercept-"));
+    process.env.CLAWNET_HOME = HOME;
+});
+afterEach(() => {
+    rmSync(HOME, { recursive: true, force: true });
+    delete process.env.CLAWNET_HOME;
+});
+describe("InboxRelay messageInterceptor", () => {
+    it("interceptor returning false: message is pushed to LLM normally", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("queen-0", fakeRole("queen-0"));
+        const store = new InboxStore("/tmp/relayInterceptProj", "sw1");
+        await store.append("queen-0", { ...baseMsg, id: "m1" });
+        const interceptor = vi.fn().mockResolvedValue(false);
+        const relay = new InboxRelay(a, () => sw, interceptor);
+        await relay.deliver("sw1", "queen-0");
+        expect(interceptor).toHaveBeenCalledTimes(1);
+        expect(interceptor).toHaveBeenCalledWith("sw1", "queen-0", expect.objectContaining({ id: "m1", type: "plan_review_result" }));
+        expect(a.sendInput).toHaveBeenCalledTimes(1);
+        const payload = a.sendInput.mock.calls[0][1];
+        expect(payload).toContain('id="m1"');
+    });
+    it("interceptor returning true: message NOT pushed; markDelivered called for that id", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("queen-0", fakeRole("queen-0"));
+        const store = new InboxStore("/tmp/relayInterceptProj", "sw1");
+        await store.append("queen-0", { ...baseMsg, id: "m1" });
+        const interceptor = vi.fn().mockResolvedValue(true);
+        const relay = new InboxRelay(a, () => sw, interceptor);
+        await relay.deliver("sw1", "queen-0");
+        expect(interceptor).toHaveBeenCalledTimes(1);
+        expect(a.sendInput).not.toHaveBeenCalled();
+        const all = await store.readAll("queen-0");
+        expect(all).toHaveLength(1);
+        expect(all[0].delivered).toBe(true);
+        expect(typeof all[0].deliveredAt).toBe("number");
+    });
+    it("mix: 2 messages, interceptor consumes 1; the other is pushed", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("queen-0", fakeRole("queen-0"));
+        const store = new InboxStore("/tmp/relayInterceptProj", "sw1");
+        await store.append("queen-0", { ...baseMsg, id: "m1" });
+        await store.append("queen-0", { ...baseMsg, id: "m2", type: "task", data: "do it" });
+        const interceptor = vi.fn(async (_sw, _inst, msg) => msg.id === "m1");
+        const relay = new InboxRelay(a, () => sw, interceptor);
+        await relay.deliver("sw1", "queen-0");
+        expect(interceptor).toHaveBeenCalledTimes(2);
+        expect(a.sendInput).toHaveBeenCalledTimes(1);
+        const payload = a.sendInput.mock.calls[0][1];
+        expect(payload).toContain('id="m2"');
+        expect(payload).not.toContain('id="m1"');
+        const all = await store.readAll("queen-0");
+        const m1 = all.find((m) => m.id === "m1");
+        const m2 = all.find((m) => m.id === "m2");
+        expect(m1.delivered).toBe(true);
+        // m2 is still delivered=false (Task 8 onAgentTurnSettled flow flips it).
+        expect(m2.delivered).toBe(false);
+    });
+    it("interceptor throws: relay logs warn, message NOT consumed (still pushed as fallback)", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("queen-0", fakeRole("queen-0"));
+        const store = new InboxStore("/tmp/relayInterceptProj", "sw1");
+        await store.append("queen-0", { ...baseMsg, id: "m1" });
+        const interceptor = vi.fn().mockRejectedValue(new Error("boom"));
+        const relay = new InboxRelay(a, () => sw, interceptor);
+        await expect(relay.deliver("sw1", "queen-0")).resolves.toBeUndefined();
+        // Fallback: message still pushed to LLM.
+        expect(a.sendInput).toHaveBeenCalledTimes(1);
+        const payload = a.sendInput.mock.calls[0][1];
+        expect(payload).toContain('id="m1"');
+        // Not auto-marked delivered (will go through normal pendingEcho flow).
+        const all = await store.readAll("queen-0");
+        expect(all[0].delivered).toBe(false);
+    });
+    it("no interceptor configured: behaviour matches pre-interceptor relay", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("queen-0", fakeRole("queen-0"));
+        const store = new InboxStore("/tmp/relayInterceptProj", "sw1");
+        await store.append("queen-0", { ...baseMsg, id: "m1" });
+        // 3rd arg omitted on purpose.
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "queen-0");
+        expect(a.sendInput).toHaveBeenCalledTimes(1);
+        const all = await store.readAll("queen-0");
+        expect(all[0].delivered).toBe(false);
+    });
+    it("consumed message stays delivered → next deliver does not re-fire interceptor", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("queen-0", fakeRole("queen-0"));
+        const store = new InboxStore("/tmp/relayInterceptProj", "sw1");
+        await store.append("queen-0", { ...baseMsg, id: "m1" });
+        const interceptor = vi.fn().mockResolvedValue(true);
+        const relay = new InboxRelay(a, () => sw, interceptor);
+        await relay.deliver("sw1", "queen-0");
+        // small yield so any settled state lands.
+        await new Promise((r) => setImmediate(r));
+        await relay.deliver("sw1", "queen-0");
+        expect(interceptor).toHaveBeenCalledTimes(1);
+        expect(a.sendInput).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=inbox-relay-interceptor.test.js.map

package/dist/__tests__/inbox-relay-interceptor.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-relay-interceptor.test.js","sourceRoot":"","sources":["../../src/__tests__/inbox-relay-interceptor.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/inbox-relay.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=inbox-relay.test.d.ts.map

package/dist/__tests__/inbox-relay.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-relay.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/inbox-relay.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/inbox-relay.test.js

@@ -0,0 +1,318 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { InboxRelay } from "../inbox-relay.js";
+import { InboxStore } from "../inbox-store.js";
+const fakeAdapter = () => ({
+    createSession: vi.fn(async () => ""),
+    sendInput: vi.fn(),
+    closeSession: vi.fn(async () => { }),
+});
+describe("InboxRelay skeleton", () => {
+    it("deliver() resolves without throwing when getSwarm returns undefined", async () => {
+        const relay = new InboxRelay(fakeAdapter(), () => undefined);
+        await expect(relay.deliver("sw", "dev-0")).resolves.toBeUndefined();
+    });
+    it("single-flight: 并发同 (swarmId, instanceId) 复用同一个 Promise", async () => {
+        let runCount = 0;
+        const relay = new InboxRelay(fakeAdapter(), () => undefined);
+        const spy = vi.spyOn(relay, "runDeliver").mockImplementation(async () => {
+            runCount++;
+            await new Promise((r) => setTimeout(r, 30));
+        });
+        const [a, b, c] = await Promise.all([
+            relay.deliver("sw", "dev-0"),
+            relay.deliver("sw", "dev-0"),
+            relay.deliver("sw", "dev-0"),
+        ]);
+        expect(runCount).toBe(1);
+        expect(a).toBeUndefined();
+        expect(b).toBeUndefined();
+        expect(c).toBeUndefined();
+        spy.mockRestore();
+    });
+    it("不同 (swarmId, instanceId) 各自独立运行", async () => {
+        const relay = new InboxRelay(fakeAdapter(), () => undefined);
+        let runCount = 0;
+        const spy = vi.spyOn(relay, "runDeliver").mockImplementation(async () => {
+            runCount++;
+            await new Promise((r) => setTimeout(r, 10));
+        });
+        await Promise.all([
+            relay.deliver("sw", "dev-0"),
+            relay.deliver("sw", "dev-1"),
+            relay.deliver("sw2", "dev-0"),
+        ]);
+        expect(runCount).toBe(3);
+        spy.mockRestore();
+    });
+    it("第一次 deliver 完成后，再调一次会重新跑（inFlight 已清理）", async () => {
+        const relay = new InboxRelay(fakeAdapter(), () => undefined);
+        let runCount = 0;
+        const spy = vi.spyOn(relay, "runDeliver").mockImplementation(async () => {
+            runCount++;
+        });
+        await relay.deliver("sw", "dev-0");
+        await relay.deliver("sw", "dev-0");
+        expect(runCount).toBe(2);
+        spy.mockRestore();
+    });
+    it("onAgentTurnSettled 不抛错（Task 8 实现）", async () => {
+        const relay = new InboxRelay(fakeAdapter(), () => undefined);
+        await expect(relay.onAgentTurnSettled("sw", "dev-0")).resolves.toBeUndefined();
+    });
+});
+let HOME;
+beforeEach(() => {
+    HOME = mkdtempSync(join(tmpdir(), "relay-gates-"));
+    process.env.CLAWNET_HOME = HOME;
+});
+afterEach(() => {
+    rmSync(HOME, { recursive: true, force: true });
+    delete process.env.CLAWNET_HOME;
+});
+const adapter = () => ({
+    createSession: vi.fn(async () => ""),
+    sendInput: vi.fn(),
+    closeSession: vi.fn(async () => { }),
+});
+const fakeSwarm = (workDir = "/tmp/relayProj", swarmId = "sw1") => ({
+    id: swarmId, hubSessionId: swarmId, workDir,
+    roles: new Map(), plan: null,
+    nextInstanceSeq: new Map(), idleCheckCount: 0, maxIdleChecks: 10,
+    isPaused: false, status: "running", planStatus: "none",
+});
+const fakeRole = (instanceId, status = "active") => ({
+    instanceId, roleName: "developer",
+    definition: { name: "developer", shortName: "dev", type: "worker", description: "", capabilities: [], color: "blue", promptBody: "" },
+    roleSessionId: `swsess::${instanceId}`,
+    status,
+});
+const baseMsg = { from: "queen", type: "task", data: "do it", timestamp: 1, delivered: false };
+describe("InboxRelay 4 gates (runDeliver)", () => {
+    it("Gate 1 liveness: swarm 不存在不调 sendInput", async () => {
+        const a = adapter();
+        const relay = new InboxRelay(a, () => undefined);
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).not.toHaveBeenCalled();
+    });
+    it("Gate 1 liveness: workDir 缺失不调 sendInput", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.workDir = undefined;
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).not.toHaveBeenCalled();
+    });
+    it("Gate 1 liveness: role 不存在不调 sendInput", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).not.toHaveBeenCalled();
+    });
+    it("Gate 2 lifecycle: status='spawning' 不调 sendInput", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0", "spawning"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1" });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).not.toHaveBeenCalled();
+    });
+    it("Gate 2 lifecycle: status='stopped' 不调 sendInput", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0", "stopped"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1" });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).not.toHaveBeenCalled();
+    });
+    it("inbox 空时不调 sendInput", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).not.toHaveBeenCalled();
+    });
+    it("通过所有门：调 sendInput 一次，payload 含 <info_for_agent> 包裹", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1", taskId: "t1" });
+        await store.append("dev-0", { ...baseMsg, id: "m2", data: "second" });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).toHaveBeenCalledTimes(1);
+        const [sid, payload] = a.sendInput.mock.calls[0];
+        expect(sid).toBe("swsess::dev-0");
+        expect(payload).toContain("<info_for_agent>");
+        expect(payload).toContain("</info_for_agent>");
+        expect(payload).toContain('id="m1"');
+        expect(payload).toContain('id="m2"');
+        expect(payload).toContain('taskId="t1"');
+        expect(payload).toContain("do it");
+        expect(payload).toContain("second");
+    });
+    it("Gate 3 pending-echo: 同 messageId 第二次 deliver 不重复推", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1" });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).toHaveBeenCalledTimes(1);
+    });
+    it("Gate 3 pending-echo: 已推送 + 新追加，第二次只推新的", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1" });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        await store.append("dev-0", { ...baseMsg, id: "m2", data: "new" });
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).toHaveBeenCalledTimes(2);
+        const second = a.sendInput.mock.calls[1][1];
+        expect(second).toContain('id="m2"');
+        expect(second).not.toContain('id="m1"');
+    });
+    it("通过门后 inbox 中消息仍是 delivered=false（Task 8 才标）", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1" });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        const all = await store.readAll("dev-0");
+        expect(all[0].delivered).toBe(false);
+    });
+});
+describe("InboxRelay XML escaping (info_for_agent envelope)", () => {
+    it("body 含 </message> 与 </info_for_agent> 时转义 '<'，不破坏 envelope", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", {
+            ...baseMsg,
+            id: "m1",
+            data: "hello </message><script>alert(1)</script></info_for_agent>",
+        });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        const payload = a.sendInput.mock.calls[0][1];
+        // 只能出现外层一对 envelope，body 内的关闭标签必须被转义。
+        const innerBodyStart = payload.indexOf('id="m1">') + 'id="m1">'.length;
+        const innerBodyEnd = payload.indexOf("</message>", innerBodyStart);
+        const innerBody = payload.slice(innerBodyStart, innerBodyEnd);
+        expect(innerBody).not.toContain("</message>");
+        expect(innerBody).not.toContain("</info_for_agent>");
+        expect(innerBody).not.toContain("<script>");
+        expect(innerBody).toContain("&lt;/message>");
+        expect(innerBody).toContain("&lt;/info_for_agent>");
+        // 外层 envelope 仍正确闭合。
+        expect(payload.match(/<info_for_agent>/g)?.length).toBe(1);
+        expect(payload.match(/<\/info_for_agent>/g)?.length).toBe(1);
+        expect(payload.match(/<\/message>/g)?.length).toBe(1);
+    });
+    it("属性 from / type / taskId / id 含 \" 与 < & 时被 HTML 属性转义", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", {
+            id: 'id"with&quote',
+            from: 'a"b<c&d',
+            type: 'ty"pe',
+            taskId: 't"1',
+            data: "ok",
+            timestamp: 1,
+            delivered: false,
+        });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        const payload = a.sendInput.mock.calls[0][1];
+        expect(payload).toContain('from="a&quot;b&lt;c&amp;d"');
+        expect(payload).toContain('type="ty&quot;pe"');
+        expect(payload).toContain('taskId="t&quot;1"');
+        expect(payload).toContain('id="id&quot;with&amp;quote"');
+        // 不存在裸 "a"b" 这种破坏性属性。
+        expect(payload).not.toContain('from="a"b');
+    });
+});
+describe("InboxRelay.onAgentTurnSettled", () => {
+    it("turn-settled 把 pendingEchoes 标记 delivered=true 并清空", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1" });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        expect((await store.readAll("dev-0"))[0].delivered).toBe(false);
+        await relay.onAgentTurnSettled("sw1", "dev-0");
+        await new Promise((r) => setTimeout(r, 20));
+        expect((await store.readAll("dev-0"))[0].delivered).toBe(true);
+    });
+    it("settled 后再次 deliver 不重推同一消息", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1" });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        await relay.onAgentTurnSettled("sw1", "dev-0");
+        await new Promise((r) => setTimeout(r, 20));
+        await relay.deliver("sw1", "dev-0");
+        expect(a.sendInput).toHaveBeenCalledTimes(1);
+    });
+    it("settled 后 turn 期间到达的新消息会被再投递", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1" });
+        const relay = new InboxRelay(a, () => sw);
+        await relay.deliver("sw1", "dev-0");
+        await store.append("dev-0", { ...baseMsg, id: "m2", data: "later" });
+        await relay.onAgentTurnSettled("sw1", "dev-0");
+        await new Promise((r) => setTimeout(r, 50));
+        expect(a.sendInput).toHaveBeenCalledTimes(2);
+        const second = a.sendInput.mock.calls[1][1];
+        expect(second).toContain('id="m2"');
+        expect(second).not.toContain('id="m1"');
+    });
+    it("pendingEchoes 为空时 settled 是 no-op", async () => {
+        const a = adapter();
+        const relay = new InboxRelay(a, () => fakeSwarm());
+        await expect(relay.onAgentTurnSettled("sw1", "dev-0")).resolves.toBeUndefined();
+        expect(a.sendInput).not.toHaveBeenCalled();
+    });
+    it("swarm 已消失时 settled 清空 pendingEchoes 不抛错", async () => {
+        const a = adapter();
+        const sw = fakeSwarm();
+        sw.roles.set("dev-0", fakeRole("dev-0"));
+        const store = new InboxStore("/tmp/relayProj", "sw1");
+        await store.append("dev-0", { ...baseMsg, id: "m1" });
+        let getSwarmReturns = sw;
+        const relay = new InboxRelay(a, () => getSwarmReturns);
+        await relay.deliver("sw1", "dev-0");
+        getSwarmReturns = undefined;
+        await expect(relay.onAgentTurnSettled("sw1", "dev-0")).resolves.toBeUndefined();
+        await expect(relay.deliver("sw1", "dev-0")).resolves.toBeUndefined();
+    });
+});
+//# sourceMappingURL=inbox-relay.test.js.map