@tjamescouch/gro 1.3.2

package/tests/memory.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Tests for AgentMemory, SimpleMemory, and AdvancedMemory.
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import type { ChatDriver, ChatMessage, ChatOutput } from "../src/drivers/types.js";
+import { SimpleMemory } from "../src/memory/simple-memory.js";
+import { AdvancedMemory } from "../src/memory/advanced-memory.js";
+
+/** Mock driver that returns a canned summary. */
+function mockDriver(response = "Summary bullet point."): ChatDriver {
+  return {
+    async chat(_msgs: ChatMessage[], _opts?: any): Promise<ChatOutput> {
+      return { text: response, toolCalls: [] };
+    },
+  };
+}
+
+/** Helper to build a message. */
+function msg(role: string, content: string, from?: string): ChatMessage {
+  return { role, content, from: from ?? role };
+}
+
+describe("SimpleMemory", () => {
+  test("stores messages in order", async () => {
+    const mem = new SimpleMemory();
+    await mem.add(msg("user", "hello"));
+    await mem.add(msg("assistant", "hi"));
+    const msgs = mem.messages();
+    assert.strictEqual(msgs.length, 2);
+    assert.strictEqual(msgs[0].content, "hello");
+    assert.strictEqual(msgs[1].content, "hi");
+  });
+
+  test("prepends system prompt", async () => {
+    const mem = new SimpleMemory("You are helpful.");
+    await mem.add(msg("user", "hello"));
+    const msgs = mem.messages();
+    assert.strictEqual(msgs.length, 2);
+    assert.strictEqual(msgs[0].role, "system");
+    assert.strictEqual(msgs[0].content, "You are helpful.");
+    assert.strictEqual(msgs[1].content, "hello");
+  });
+
+  test("empty system prompt is not added", async () => {
+    const mem = new SimpleMemory("   ");
+    const msgs = mem.messages();
+    assert.strictEqual(msgs.length, 0);
+  });
+
+  test("addIfNotExists deduplicates", async () => {
+    const mem = new SimpleMemory();
+    await mem.add(msg("user", "hello"));
+    await mem.addIfNotExists(msg("user", "hello"));
+    await mem.addIfNotExists(msg("user", "world"));
+    const msgs = mem.messages();
+    assert.strictEqual(msgs.length, 2);
+    assert.strictEqual(msgs[1].content, "world");
+  });
+
+  test("messages() returns a copy", async () => {
+    const mem = new SimpleMemory();
+    await mem.add(msg("user", "hello"));
+    const msgs = mem.messages();
+    msgs.push(msg("user", "injected"));
+    assert.strictEqual(mem.messages().length, 1);
+  });
+
+  test("load and save are no-ops", async () => {
+    const mem = new SimpleMemory();
+    await mem.load("test-id");
+    await mem.save("test-id");
+    // No error thrown
+  });
+});
+
+describe("AdvancedMemory", () => {
+  test("stores messages when under budget", async () => {
+    const mem = new AdvancedMemory({
+      driver: mockDriver(),
+      model: "test-model",
+      contextTokens: 100_000,
+    });
+    await mem.add(msg("user", "hello"));
+    await mem.add(msg("assistant", "hi"));
+    const msgs = mem.messages();
+    assert.strictEqual(msgs.length, 2);
+  });
+
+  test("includes system prompt", async () => {
+    const mem = new AdvancedMemory({
+      driver: mockDriver(),
+      model: "test-model",
+      systemPrompt: "Be helpful.",
+    });
+    await mem.add(msg("user", "hello"));
+    const msgs = mem.messages();
+    assert.strictEqual(msgs[0].role, "system");
+    assert.strictEqual(msgs[0].content, "Be helpful.");
+  });
+
+  test("triggers compaction when budget exceeded", async () => {
+    const mem = new AdvancedMemory({
+      driver: mockDriver(),
+      model: "test-model",
+      contextTokens: 4096,
+      reserveHeaderTokens: 200,
+      reserveResponseTokens: 200,
+      avgCharsPerToken: 4,
+      highRatio: 0.70,
+      lowRatio: 0.50,
+      keepRecentPerLane: 2,
+    });
+
+    // Add enough messages to exceed the high watermark.
+    // Budget = 3696 tokens. High = 2587 tokens = ~10348 chars.
+    // Each msg pair ~200 chars + 64 overhead = ~264 chars.
+    // Need ~40 pairs to exceed.
+    for (let i = 0; i < 60; i++) {
+      await mem.add(msg("user", `Message number ${i} with padding text to use up token budget quickly.`));
+      await mem.add(msg("assistant", `Reply number ${i} acknowledging the user's message with detail.`));
+    }
+
+    // After compaction (summarization or pruning), buffer should be smaller
+    const msgs = mem.messages();
+    assert.ok(msgs.length < 120, `Expected compaction to reduce messages, got ${msgs.length}`);
+    // Should still have some messages (not empty)
+    assert.ok(msgs.length > 0, "Buffer should not be empty after compaction");
+  });
+
+  test("preserves system prompt during summarization", async () => {
+    const mem = new AdvancedMemory({
+      driver: mockDriver(),
+      model: "test-model",
+      systemPrompt: "Critical instruction.",
+      contextTokens: 2048,
+      avgCharsPerToken: 4,
+      keepRecentPerLane: 1,
+    });
+
+    for (let i = 0; i < 30; i++) {
+      await mem.add(msg("user", `User msg ${i} with padding to fill the budget up.`));
+      await mem.add(msg("assistant", `Assistant reply ${i} also with padding text.`));
+    }
+
+    const msgs = mem.messages();
+    const systemMsgs = msgs.filter(m => m.role === "system");
+    assert.ok(systemMsgs.length > 0, "System messages should be preserved after summarization");
+  });
+
+  test("handles tool messages", async () => {
+    const mem = new AdvancedMemory({
+      driver: mockDriver(),
+      model: "test-model",
+      contextTokens: 100_000,
+      keepRecentTools: 2,
+    });
+
+    await mem.add(msg("user", "Run the tool"));
+    await mem.add({ role: "tool", content: "tool result 1", from: "tool", tool_call_id: "tc1" });
+    await mem.add({ role: "tool", content: "tool result 2", from: "tool", tool_call_id: "tc2" });
+    await mem.add(msg("assistant", "Got it"));
+
+    const msgs = mem.messages();
+    const toolMsgs = msgs.filter(m => m.role === "tool");
+    assert.strictEqual(toolMsgs.length, 2);
+  });
+
+  test("config clamps extreme values", async () => {
+    // This shouldn't throw — extreme values get clamped
+    const mem = new AdvancedMemory({
+      driver: mockDriver(),
+      model: "test-model",
+      contextTokens: 100,       // gets clamped to 2048
+      highRatio: 99,             // clamped to 0.95
+      lowRatio: -5,              // clamped to 0.35
+      summaryRatio: 999,         // clamped to 0.50
+      avgCharsPerToken: 0.1,     // clamped to 1.5
+      keepRecentPerLane: -1,     // clamped to 1
+      keepRecentTools: -10,      // clamped to 0
+    });
+    await mem.add(msg("user", "still works"));
+    assert.strictEqual(mem.messages().length, 1);
+  });
+});

package/tests/rate-limiter.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Tests for RateLimiter.
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import { rateLimiter } from "../src/utils/rate-limiter.js";
+
+describe("RateLimiter", () => {
+  test("first call returns immediately", async () => {
+    rateLimiter.reset("test-immediate");
+    const start = Date.now();
+    await rateLimiter.limit("test-immediate", 10);
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed < 200, `First call should be near-instant, took ${elapsed}ms`);
+  });
+
+  test("second call is delayed", async () => {
+    rateLimiter.reset("test-delay");
+    await rateLimiter.limit("test-delay", 2); // 2 per second = 500ms interval
+    const start = Date.now();
+    await rateLimiter.limit("test-delay", 2);
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed >= 400, `Second call should wait ~500ms, took ${elapsed}ms`);
+    assert.ok(elapsed < 800, `Should not wait too long, took ${elapsed}ms`);
+  });
+
+  test("different keys are independent", async () => {
+    rateLimiter.reset();
+    await rateLimiter.limit("key-a", 1);
+    const start = Date.now();
+    await rateLimiter.limit("key-b", 1); // different key, no wait
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed < 200, `Different key should not wait, took ${elapsed}ms`);
+  });
+
+  test("throws on invalid throughput", async () => {
+    await assert.rejects(
+      () => rateLimiter.limit("bad", 0),
+      /positive finite number/
+    );
+    await assert.rejects(
+      () => rateLimiter.limit("bad", -1),
+      /positive finite number/
+    );
+    await assert.rejects(
+      () => rateLimiter.limit("bad", Infinity),
+      /positive finite number/
+    );
+    await assert.rejects(
+      () => rateLimiter.limit("bad", NaN),
+      /positive finite number/
+    );
+  });
+
+  test("reset clears state", async () => {
+    rateLimiter.reset("test-reset");
+    await rateLimiter.limit("test-reset", 1); // first call
+    rateLimiter.reset("test-reset"); // reset
+    const start = Date.now();
+    await rateLimiter.limit("test-reset", 1); // should be instant after reset
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed < 200, `After reset should be instant, took ${elapsed}ms`);
+  });
+
+  test("reset() without args clears all keys", async () => {
+    await rateLimiter.limit("x1", 1);
+    await rateLimiter.limit("x2", 1);
+    rateLimiter.reset();
+    const start = Date.now();
+    await rateLimiter.limit("x1", 1);
+    await rateLimiter.limit("x2", 1);
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed < 200, `After global reset both should be instant, took ${elapsed}ms`);
+  });
+});

package/tests/retry.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Tests for retry utilities.
+ *
+ * Covers: isRetryable, retryDelay, sleep, MAX_RETRIES, RETRY_BASE_MS
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import { isRetryable, retryDelay, sleep, MAX_RETRIES, RETRY_BASE_MS } from "../src/utils/retry.js";
+
+// ---------------------------------------------------------------------------
+// isRetryable
+// ---------------------------------------------------------------------------
+
+describe("isRetryable", () => {
+  test("429 (rate limited) is retryable", () => {
+    assert.strictEqual(isRetryable(429), true);
+  });
+
+  test("502 (bad gateway) is retryable", () => {
+    assert.strictEqual(isRetryable(502), true);
+  });
+
+  test("503 (service unavailable) is retryable", () => {
+    assert.strictEqual(isRetryable(503), true);
+  });
+
+  test("529 (overloaded) is retryable", () => {
+    assert.strictEqual(isRetryable(529), true);
+  });
+
+  test("200 is not retryable", () => {
+    assert.strictEqual(isRetryable(200), false);
+  });
+
+  test("400 (bad request) is not retryable", () => {
+    assert.strictEqual(isRetryable(400), false);
+  });
+
+  test("401 (unauthorized) is not retryable", () => {
+    assert.strictEqual(isRetryable(401), false);
+  });
+
+  test("403 (forbidden) is not retryable", () => {
+    assert.strictEqual(isRetryable(403), false);
+  });
+
+  test("404 (not found) is not retryable", () => {
+    assert.strictEqual(isRetryable(404), false);
+  });
+
+  test("500 (internal server error) is not retryable", () => {
+    assert.strictEqual(isRetryable(500), false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// retryDelay
+// ---------------------------------------------------------------------------
+
+describe("retryDelay", () => {
+  test("attempt 0 returns delay in [1000, 1500) range", () => {
+    // base = 1000 * 2^0 = 1000, jitter = [0, 500)
+    for (let i = 0; i < 100; i++) {
+      const delay = retryDelay(0);
+      assert.ok(delay >= 1000, `delay ${delay} should be >= 1000`);
+      assert.ok(delay < 1500, `delay ${delay} should be < 1500`);
+    }
+  });
+
+  test("attempt 1 returns delay in [2000, 3000) range", () => {
+    // base = 1000 * 2^1 = 2000, jitter = [0, 1000)
+    for (let i = 0; i < 100; i++) {
+      const delay = retryDelay(1);
+      assert.ok(delay >= 2000, `delay ${delay} should be >= 2000`);
+      assert.ok(delay < 3000, `delay ${delay} should be < 3000`);
+    }
+  });
+
+  test("attempt 2 returns delay in [4000, 6000) range", () => {
+    // base = 1000 * 2^2 = 4000, jitter = [0, 2000)
+    for (let i = 0; i < 100; i++) {
+      const delay = retryDelay(2);
+      assert.ok(delay >= 4000, `delay ${delay} should be >= 4000`);
+      assert.ok(delay < 6000, `delay ${delay} should be < 6000`);
+    }
+  });
+
+  test("delay increases with attempt number (exponential)", () => {
+    // Run enough samples that minimum of higher attempt > maximum of lower attempt (statistically)
+    const delays0 = Array.from({ length: 50 }, () => retryDelay(0));
+    const delays2 = Array.from({ length: 50 }, () => retryDelay(2));
+    const max0 = Math.max(...delays0);
+    const min2 = Math.min(...delays2);
+    assert.ok(min2 > max0, `min attempt-2 delay (${min2}) should exceed max attempt-0 delay (${max0})`);
+  });
+
+  test("includes jitter (not always the same value)", () => {
+    const delays = Array.from({ length: 20 }, () => retryDelay(0));
+    const unique = new Set(delays);
+    assert.ok(unique.size > 1, "delays should vary due to jitter");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// sleep
+// ---------------------------------------------------------------------------
+
+describe("sleep", () => {
+  test("resolves after approximately the specified duration", async () => {
+    const start = Date.now();
+    await sleep(50);
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed >= 40, `should wait at least ~50ms, took ${elapsed}ms`);
+    assert.ok(elapsed < 200, `should not wait too long, took ${elapsed}ms`);
+  });
+
+  test("sleep(0) resolves nearly immediately", async () => {
+    const start = Date.now();
+    await sleep(0);
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed < 50, `sleep(0) should be near-instant, took ${elapsed}ms`);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+describe("retry constants", () => {
+  test("MAX_RETRIES is 3", () => {
+    assert.strictEqual(MAX_RETRIES, 3);
+  });
+
+  test("RETRY_BASE_MS is 1000", () => {
+    assert.strictEqual(RETRY_BASE_MS, 1000);
+  });
+});

package/tests/timed-fetch.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for timedFetch.
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import http from "http";
+import { timedFetch } from "../src/utils/timed-fetch.js";
+
+function startServer(handler: http.RequestListener): Promise<{ port: number; close: () => Promise<void> }> {
+  return new Promise((resolve) => {
+    const server = http.createServer(handler);
+    server.listen(0, () => {
+      const port = (server.address() as any).port;
+      resolve({
+        port,
+        close: () => new Promise<void>((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+describe("timedFetch", () => {
+  test("successful GET", async () => {
+    const srv = await startServer((_req, res) => {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ ok: true }));
+    });
+
+    try {
+      const res = await timedFetch(`http://localhost:${srv.port}/`, {
+        where: "test",
+      });
+      assert.strictEqual(res.status, 200);
+      const data = await res.json() as any;
+      assert.strictEqual(data.ok, true);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  test("successful POST with body", async () => {
+    const srv = await startServer((req, res) => {
+      let body = "";
+      req.on("data", (d: Buffer) => (body += d.toString()));
+      req.on("end", () => {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ echo: body }));
+      });
+    });
+
+    try {
+      const res = await timedFetch(`http://localhost:${srv.port}/`, {
+        method: "POST",
+        body: "hello",
+        where: "test-post",
+      });
+      assert.strictEqual(res.status, 200);
+      const data = await res.json() as any;
+      assert.strictEqual(data.echo, "hello");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  test("timeout triggers abort", async () => {
+    const srv = await startServer((_req, _res) => {
+      // Never respond — simulate hang
+    });
+
+    try {
+      await assert.rejects(
+        () =>
+          timedFetch(`http://localhost:${srv.port}/`, {
+            timeoutMs: 100,
+            where: "test-timeout",
+          }),
+        (err: any) => {
+          assert.ok(err.message.includes("fetch timeout"), `Expected timeout error, got: ${err.message}`);
+          return true;
+        }
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  test("no timeout when timeoutMs is 0", async () => {
+    const srv = await startServer((_req, res) => {
+      res.writeHead(200);
+      res.end("ok");
+    });
+
+    try {
+      const res = await timedFetch(`http://localhost:${srv.port}/`, {
+        timeoutMs: 0,
+        where: "test-no-timeout",
+      });
+      assert.strictEqual(res.status, 200);
+    } finally {
+      await srv.close();
+    }
+  });
+});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}