@nookplot/runtime 0.5.131 → 0.5.132

package/dist/__tests__/autonomous.loadedSkillRefs.test.js

@@ -0,0 +1,150 @@
+/**
+ * SRA Phase 4b — loadedSkillRefs capture + flush.
+ *
+ * The runtime SDK records every nookplot_load_skill call's canonical_ref +
+ * kind, then flushes the buffer into the payload of the next
+ * submit_reasoning_trace / submit_subtask_trace call. This is the producer
+ * side that lets the gateway's intersection logic write trace_id onto the
+ * agent's recent skill_utility_signals rows. Without this, the utility
+ * prior reads zero rows and every candidate gets the cold-start prior 0.4.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createMockRuntime } from "./helpers/mockRuntime.js";
+import { AutonomousAgent } from "../autonomous.js";
+vi.mock("../signing.js", () => ({
+    prepareSignRelay: vi.fn().mockResolvedValue({ txHash: "0xRELAY_TX" }),
+    signForwardRequest: vi.fn().mockResolvedValue("0xSIGNATURE"),
+}));
+let runtime;
+let callbacks;
+let agent;
+let requestMock;
+beforeEach(() => {
+    vi.clearAllMocks();
+    const mock = createMockRuntime();
+    runtime = mock.runtime;
+    callbacks = mock.callbacks;
+    requestMock = runtime.connection.request;
+    requestMock.mockImplementation(async (method, path, body) => {
+        if (method === "POST" && path === "/v1/actions/execute") {
+            const { toolName } = (body ?? {});
+            if (toolName === "nookplot_load_skill") {
+                // Echo a load result with canonical_ref — payload's `kind` arg drives kind.
+                return {
+                    status: "completed",
+                    result: {
+                        kind: "community",
+                        canonical_ref: "abc-123-uuid",
+                        content: "skill content",
+                    },
+                };
+            }
+            return { status: "completed", result: { id: "submission_xyz" } };
+        }
+        return { success: true };
+    });
+    agent = new AutonomousAgent(runtime, { verbose: false });
+    agent.start();
+});
+async function dispatchAction(actionType, payload) {
+    callbacks.actionCb({ agentId: "agent_1", actionType, payload });
+    await new Promise((r) => setTimeout(r, 20));
+}
+function getDispatchedPayload(callIndex) {
+    const call = requestMock.mock.calls[callIndex];
+    return (call[2].payload) ?? {};
+}
+describe("SRA loadedSkillRefs capture + flush", () => {
+    it("captures canonical_ref from load_skill result and flushes on submit_reasoning_trace", async () => {
+        await dispatchAction("load_skill", { name: "mining", kind: "community" });
+        await dispatchAction("submit_reasoning_trace", {
+            challengeId: "ch_1",
+            traceCid: "Qm...",
+            traceHash: "abc",
+        });
+        const submitPayload = getDispatchedPayload(1);
+        expect(submitPayload.loadedSkillRefs).toEqual(["community:abc-123-uuid"]);
+    });
+    it("flushes multiple loaded skills as `${kind}:${ref}` array", async () => {
+        // First load — community kind, ref X.
+        requestMock.mockImplementationOnce(async () => ({
+            status: "completed",
+            result: { kind: "community", canonical_ref: "uuid-A" },
+        }));
+        await dispatchAction("load_skill", { name: "mining", kind: "community" });
+        // Second load — mcp_tool kind, ref Y.
+        requestMock.mockImplementationOnce(async () => ({
+            status: "completed",
+            result: { kind: "mcp_tool", canonical_ref: "nookplot_create_post" },
+        }));
+        await dispatchAction("load_skill", { name: "nookplot_create_post", kind: "mcp_tool" });
+        await dispatchAction("submit_reasoning_trace", { challengeId: "ch_1" });
+        const submitPayload = getDispatchedPayload(2);
+        expect(submitPayload.loadedSkillRefs).toEqual([
+            "community:uuid-A",
+            "mcp_tool:nookplot_create_post",
+        ]);
+    });
+    it("flushes on submit_subtask_trace too", async () => {
+        await dispatchAction("load_skill", { name: "mining", kind: "community" });
+        await dispatchAction("submit_subtask_trace", {
+            challengeId: "ch_1",
+            subtaskOrdinal: 1,
+            guildId: 5,
+        });
+        const submitPayload = getDispatchedPayload(1);
+        expect(submitPayload.loadedSkillRefs).toEqual(["community:abc-123-uuid"]);
+    });
+    it("does not inject loadedSkillRefs when buffer is empty", async () => {
+        await dispatchAction("submit_reasoning_trace", { challengeId: "ch_1" });
+        const submitPayload = getDispatchedPayload(0);
+        expect(submitPayload.loadedSkillRefs).toBeUndefined();
+    });
+    it("respects caller-provided loadedSkillRefs (does not overwrite)", async () => {
+        await dispatchAction("load_skill", { name: "mining", kind: "community" });
+        await dispatchAction("submit_reasoning_trace", {
+            challengeId: "ch_1",
+            loadedSkillRefs: ["protocol_skill:custom-ref"],
+        });
+        const submitPayload = getDispatchedPayload(1);
+        expect(submitPayload.loadedSkillRefs).toEqual(["protocol_skill:custom-ref"]);
+    });
+    it("does not capture from non-load_skill results", async () => {
+        // search_skills returns candidates but is not a load — should not buffer.
+        requestMock.mockImplementationOnce(async () => ({
+            status: "completed",
+            result: { candidates: [{ name: "x", canonical_ref: "uuid-search" }] },
+        }));
+        await dispatchAction("search_skills", { query: "test" });
+        await dispatchAction("submit_reasoning_trace", { challengeId: "ch_1" });
+        const submitPayload = getDispatchedPayload(1);
+        expect(submitPayload.loadedSkillRefs).toBeUndefined();
+    });
+    it("caps buffer at 64 entries (drops oldest)", async () => {
+        for (let i = 0; i < 70; i++) {
+            requestMock.mockImplementationOnce(async () => ({
+                status: "completed",
+                result: { kind: "community", canonical_ref: `uuid-${i}` },
+            }));
+            await dispatchAction("load_skill", { name: `skill-${i}`, kind: "community" });
+        }
+        await dispatchAction("submit_reasoning_trace", { challengeId: "ch_1" });
+        const submitPayload = getDispatchedPayload(70);
+        const refs = submitPayload.loadedSkillRefs;
+        expect(refs).toHaveLength(64);
+        // Oldest dropped: first kept ref is the 7th (index 6) = uuid-6.
+        expect(refs[0]).toBe("community:uuid-6");
+        expect(refs[63]).toBe("community:uuid-69");
+    });
+    it("ignores load_skill responses without canonical_ref", async () => {
+        requestMock.mockImplementationOnce(async () => ({
+            status: "completed",
+            result: { kind: "community" }, // missing canonical_ref
+        }));
+        await dispatchAction("load_skill", { name: "broken", kind: "community" });
+        await dispatchAction("submit_reasoning_trace", { challengeId: "ch_1" });
+        const submitPayload = getDispatchedPayload(1);
+        expect(submitPayload.loadedSkillRefs).toBeUndefined();
+    });
+});
+//# sourceMappingURL=autonomous.loadedSkillRefs.test.js.map

package/dist/__tests__/autonomous.loadedSkillRefs.test.js.map

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

package/dist/__tests__/chatEngine.episodicHook.test.d.ts

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

package/dist/__tests__/chatEngine.episodicHook.test.d.ts.map

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

package/dist/__tests__/chatEngine.episodicHook.test.js

@@ -0,0 +1,160 @@
+/**
+ * ChatEngine × episodic-memory hook regression test.
+ *
+ * Phase 1 moved the inline `runtime.memory.storeMemory("episodic", …)` call
+ * out of `chatEngine.ts` and into `installEpisodicMemoryHook()`, fired via
+ * the `chat_turn_complete` event. These tests prove:
+ *   - the hook fires once per turn, with the documented payload shape
+ *   - `installEpisodicMemoryHook(runtime)` reproduces the prior write
+ *   - chat() returns BEFORE the memory write resolves (fire-and-forget)
+ *   - opt-out (no auto-install + no manual install) means no memory write
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+vi.mock("node:fs/promises", () => ({
+    readFile: vi.fn().mockRejectedValue(new Error("ENOENT")),
+}));
+vi.mock("../actionCatalog.js", () => ({
+    ACTION_CATALOG: {},
+    formatActionsForPrompt: vi.fn().mockReturnValue(""),
+    getCategoryListing: vi.fn().mockReturnValue([]),
+    getToolsInCategory: vi.fn().mockReturnValue([]),
+}));
+vi.mock("../signalActionMap.js", () => ({ CORE_ACTIONS: [] }));
+vi.mock("../contentSafety.js", () => ({
+    sanitizeForPrompt: vi.fn((s) => s),
+    UNTRUSTED_CONTENT_INSTRUCTION: "",
+}));
+import { ChatEngine } from "../chat/chatEngine.js";
+import { HookRegistry } from "../hooks.js";
+import { installEpisodicMemoryHook } from "../episodicMemoryHook.js";
+function makeRuntimeMock(opts) {
+    const hooks = new HookRegistry();
+    const storeMemory = vi.fn(opts?.storeMemoryImpl ?? (() => Promise.resolve({ id: "mem_1" })));
+    return {
+        runtime: {
+            hooks,
+            connection: {
+                request: vi.fn().mockResolvedValue({}),
+            },
+            memory: {
+                storeMemory,
+                recall: vi.fn().mockResolvedValue([]),
+            },
+            economy: {
+                getBalance: vi.fn().mockResolvedValue({
+                    credits: { available: 1000, total: 1000, pending: 0 },
+                }),
+                inference: vi.fn().mockResolvedValue({ content: "hello back" }),
+            },
+            events: { subscribe: vi.fn() },
+            identity: { getAddress: vi.fn().mockReturnValue("0xtest") },
+        },
+        hooks,
+        storeMemory,
+    };
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+describe("chatEngine fires chat_turn_complete", () => {
+    it("emits exactly once per chat() call with the documented payload shape", async () => {
+        const { runtime, hooks } = makeRuntimeMock();
+        const captured = [];
+        hooks.register("chat_turn_complete", (p) => { captured.push(p); });
+        const engine = new ChatEngine(runtime, {
+            generateResponse: async () => "hi there",
+            enableMemory: true,
+            enableTools: false,
+        });
+        await engine.chat("hello", { platform: "telegram", senderName: "alice", senderId: "u1" });
+        await new Promise((r) => setTimeout(r, 5));
+        expect(captured).toHaveLength(1);
+        const p = captured[0];
+        expect(p.sender).toBe("alice");
+        expect(p.platform).toBe("telegram");
+        expect(p.message).toBe("hello");
+        expect(p.response).toBe("hi there");
+        expect(p.toolsUsed).toBe(false);
+        expect(p.toolCallCount).toBe(0);
+        expect(p.senderId).toBe("u1");
+        expect(p.enableMemory).toBe(true);
+        expect(p.agentName).toBe("Agent");
+    });
+    it("installEpisodicMemoryHook calls storeMemory with the prior payload shape", async () => {
+        const { runtime, hooks, storeMemory } = makeRuntimeMock();
+        installEpisodicMemoryHook(runtime, { hooks });
+        const engine = new ChatEngine(runtime, {
+            generateResponse: async () => "response body",
+            enableMemory: true,
+            enableTools: false,
+        });
+        await engine.chat("message body", {
+            platform: "telegram", senderName: "alice", senderId: "u1", channelId: "ch1",
+        });
+        await new Promise((r) => setTimeout(r, 5));
+        expect(storeMemory).toHaveBeenCalledTimes(1);
+        const args = storeMemory.mock.calls[0];
+        const tier = args[0];
+        const content = args[1];
+        const options = args[2];
+        expect(tier).toBe("episodic");
+        expect(content).toBe("[telegram] alice: message body\nAgent: response body");
+        expect(options.tags).toContain("conversation");
+        expect(options.tags).toContain("telegram");
+        expect(options.metadata.platform).toBe("telegram");
+        expect(options.metadata.senderId).toBe("u1");
+        expect(options.metadata.senderName).toBe("alice");
+        expect(options.metadata.channelId).toBe("ch1");
+        expect(options.metadata.toolsUsed).toBe(false);
+        expect(options.metadata.toolCallCount).toBe(0);
+        expect(options.metadata.messageLength).toBe("message body".length);
+        expect(options.metadata.responseLength).toBe("response body".length);
+        expect(typeof options.metadata.timestamp).toBe("string");
+    });
+    it("WITHOUT the hook installed, no memory write happens", async () => {
+        const { runtime, storeMemory } = makeRuntimeMock();
+        // No installEpisodicMemoryHook call → opt-out semantics.
+        const engine = new ChatEngine(runtime, {
+            generateResponse: async () => "response",
+            enableMemory: true,
+            enableTools: false,
+        });
+        await engine.chat("hello", { platform: "terminal" });
+        await new Promise((r) => setTimeout(r, 5));
+        expect(storeMemory).not.toHaveBeenCalled();
+    });
+    it("chat() returns BEFORE the memory write resolves (fire-and-forget)", async () => {
+        let memoryResolved = false;
+        const { runtime, hooks } = makeRuntimeMock({
+            // never resolves until we say so
+            storeMemoryImpl: () => new Promise((res) => {
+                setTimeout(() => { memoryResolved = true; res({ id: "mem_late" }); }, 200);
+            }),
+        });
+        installEpisodicMemoryHook(runtime, { hooks });
+        const engine = new ChatEngine(runtime, {
+            generateResponse: async () => "hi",
+            enableMemory: true,
+            enableTools: false,
+        });
+        const t0 = Date.now();
+        const reply = await engine.chat("hey", { platform: "terminal" });
+        const elapsed = Date.now() - t0;
+        expect(reply).toBe("hi");
+        expect(memoryResolved).toBe(false);
+        expect(elapsed).toBeLessThan(150);
+    });
+    it("enableMemory: false suppresses the storeMemory call", async () => {
+        const { runtime, hooks, storeMemory } = makeRuntimeMock();
+        installEpisodicMemoryHook(runtime, { hooks });
+        const engine = new ChatEngine(runtime, {
+            generateResponse: async () => "hi",
+            enableMemory: false,
+            enableTools: false,
+        });
+        await engine.chat("hello", { platform: "terminal" });
+        await new Promise((r) => setTimeout(r, 5));
+        expect(storeMemory).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=chatEngine.episodicHook.test.js.map

package/dist/__tests__/chatEngine.episodicHook.test.js.map

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

package/dist/__tests__/chatEngine.test.d.ts

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

package/dist/__tests__/chatEngine.test.d.ts.map

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