talon-agent 1.0.0 → 1.2.0

package/src/__tests__/gateway-http.test.ts

@@ -1,7 +1,18 @@
-import { describe, it, expect, beforeAll, afterAll, beforeEach, vi } from "vitest";
+import {
+  describe,
+  it,
+  expect,
+  beforeAll,
+  afterAll,
+  beforeEach,
+  vi,
+} from "vitest";
 
 vi.mock("../util/log.js", () => ({
-  log: vi.fn(), logError: vi.fn(), logWarn: vi.fn(), logDebug: vi.fn(),
+  log: vi.fn(),
+  logError: vi.fn(),
+  logWarn: vi.fn(),
+  logDebug: vi.fn(),
 }));
 
 vi.mock("../core/plugin.js", () => ({
@@ -10,7 +21,10 @@ vi.mock("../core/plugin.js", () => ({
 
 vi.mock("../util/watchdog.js", () => ({
   getHealthStatus: vi.fn(() => ({
-    healthy: true, totalMessagesProcessed: 0, recentErrorCount: 0, msSinceLastMessage: 0,
+    healthy: true,
+    totalMessagesProcessed: 0,
+    recentErrorCount: 0,
+    msSinceLastMessage: 0,
   })),
 }));
 
@@ -29,7 +43,10 @@ vi.mock("../storage/cron-store.js", () => ({
   getCronJobsForChat: vi.fn(() => []),
   updateCronJob: vi.fn(),
   deleteCronJob: vi.fn(),
-  validateCronExpression: vi.fn(() => ({ valid: true, next: new Date().toISOString() })),
+  validateCronExpression: vi.fn(() => ({
+    valid: true,
+    next: new Date().toISOString(),
+  })),
   generateCronId: vi.fn(() => "test-id"),
   loadCronJobs: vi.fn(),
 }));
@@ -46,7 +63,8 @@ let port: number;
 // Mock frontend handler
 const mockFrontendHandler = vi.fn(async (body: Record<string, unknown>) => {
   const action = body.action as string;
-  if (action === "send_message") return { ok: true, message_id: 42, text: "sent" };
+  if (action === "send_message")
+    return { ok: true, message_id: 42, text: "sent" };
   if (action === "get_chat_info") return { ok: true, id: 123, type: "private" };
   return null;
 });
@@ -70,13 +88,18 @@ beforeEach(() => {
   mockFrontendHandler.mockClear();
 });
 
-async function post(body: Record<string, unknown>): Promise<{ status: number; body: Record<string, unknown> }> {
+async function post(
+  body: Record<string, unknown>,
+): Promise<{ status: number; body: Record<string, unknown> }> {
   const resp = await fetch(`http://127.0.0.1:${port}/action`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body),
   });
-  return { status: resp.status, body: await resp.json() as Record<string, unknown> };
+  return {
+    status: resp.status,
+    body: (await resp.json()) as Record<string, unknown>,
+  };
 }
 
 describe("gateway HTTP server", () => {
@@ -84,7 +107,7 @@ describe("gateway HTTP server", () => {
     it("returns health JSON", async () => {
       const resp = await fetch(`http://127.0.0.1:${port}/health`);
       expect(resp.status).toBe(200);
-      const data = await resp.json() as Record<string, unknown>;
+      const data = (await resp.json()) as Record<string, unknown>;
       expect(data.ok).toBeDefined();
       expect(data.uptime).toBeDefined();
       expect(data.memory).toBeDefined();
@@ -111,7 +134,7 @@ describe("gateway HTTP server", () => {
         body: "not valid json{{{",
       });
       expect(resp.status).toBe(400);
-      const data = await resp.json() as Record<string, unknown>;
+      const data = (await resp.json()) as Record<string, unknown>;
       expect(data.ok).toBe(false);
       expect(data.error).toContain("Invalid JSON");
     });
@@ -133,7 +156,11 @@ describe("gateway HTTP server", () => {
 
     it("routes to frontend handler", async () => {
       gateway.setContext(123);
-      const { body } = await post({ action: "send_message", _chatId: "123", text: "hello" });
+      const { body } = await post({
+        action: "send_message",
+        _chatId: "123",
+        text: "hello",
+      });
       expect(body.ok).toBe(true);
       expect(body.message_id).toBe(42);
       expect(mockFrontendHandler).toHaveBeenCalled();
@@ -142,7 +169,10 @@ describe("gateway HTTP server", () => {
 
     it("returns error for unknown action", async () => {
       gateway.setContext(123);
-      const { body } = await post({ action: "completely_unknown_action", _chatId: "123" });
+      const { body } = await post({
+        action: "completely_unknown_action",
+        _chatId: "123",
+      });
       expect(body.ok).toBe(false);
       expect(body.error).toContain("Unknown action");
       gateway.clearContext(123);
@@ -184,21 +214,35 @@ describe("gateway HTTP server", () => {
     it("one chat's context doesn't affect another", async () => {
       gateway.setContext(300);
       // Chat 400 has no context
-      const { body } = await post({ action: "send_message", _chatId: "400", text: "no context" });
+      const { body } = await post({
+        action: "send_message",
+        _chatId: "400",
+        text: "no context",
+      });
       expect(body.ok).toBe(false);
       expect(body.error).toContain("No active chat context");
       // Chat 300 still works
-      const r2 = await post({ action: "send_message", _chatId: "300", text: "still works" });
+      const r2 = await post({
+        action: "send_message",
+        _chatId: "300",
+        text: "still works",
+      });
       expect(r2.body.ok).toBe(true);
       gateway.clearContext(300);
     });
 
     it("frontend handler error returns error result (doesn't crash server)", async () => {
-      const errorHandler = vi.fn(async () => { throw new Error("handler exploded"); });
+      const errorHandler = vi.fn(async () => {
+        throw new Error("handler exploded");
+      });
       gateway.setFrontendHandler(errorHandler);
       gateway.setContext(123);
 
-      const { status, body } = await post({ action: "send_message", _chatId: "123", text: "boom" });
+      const { status, body } = await post({
+        action: "send_message",
+        _chatId: "123",
+        text: "boom",
+      });
 
       expect(status).toBe(200); // HTTP 200, error in body
       expect(body.ok).toBe(false);
@@ -210,17 +254,48 @@ describe("gateway HTTP server", () => {
 
     it("request without _chatId is rejected", async () => {
       gateway.setContext(123);
-      const { body } = await post({ action: "send_message", text: "no chatId" });
+      const { body } = await post({
+        action: "send_message",
+        text: "no chatId",
+      });
       expect(body.ok).toBe(false);
       expect(body.error).toContain("No active chat context");
       gateway.clearContext(123);
     });
+
+    it("returns 500 when handleAction result cannot be JSON-serialized", async () => {
+      // Make frontendHandler return a circular reference so JSON.stringify throws
+      const circular: Record<string, unknown> = {};
+      circular["self"] = circular;
+      const circularHandler = vi.fn(
+        async () => circular,
+      ) as unknown as import("../core/types.js").FrontendActionHandler;
+      gateway.setFrontendHandler(circularHandler);
+      gateway.setContext(123);
+
+      const { status, body } = await post({
+        action: "send_message",
+        _chatId: "123",
+        text: "boom",
+      });
+
+      expect(status).toBe(500);
+      expect(body.ok).toBe(false);
+      expect(body.error).toBeTruthy();
+
+      gateway.clearContext(123);
+      gateway.setFrontendHandler(mockFrontendHandler); // restore
+    });
   });
 
   describe("shared actions via HTTP", () => {
     it("fetch_url rejects invalid URLs", async () => {
       gateway.setContext(123);
-      const { body } = await post({ action: "fetch_url", _chatId: "123", url: "not-a-url" });
+      const { body } = await post({
+        action: "fetch_url",
+        _chatId: "123",
+        url: "not-a-url",
+      });
       expect(body.ok).toBe(false);
       gateway.clearContext(123);
     });
@@ -235,11 +310,127 @@ describe("gateway HTTP server", () => {
     it("create_cron_job works", async () => {
       gateway.setContext(123);
       const { body } = await post({
-        action: "create_cron_job", _chatId: "123",
-        name: "test", schedule: "0 9 * * *", type: "message", content: "hello",
+        action: "create_cron_job",
+        _chatId: "123",
+        name: "test",
+        schedule: "0 9 * * *",
+        type: "message",
+        content: "hello",
       });
       expect(body.ok).toBe(true);
       gateway.clearContext(123);
     });
   });
 });
+
+// ── Plugin action route coverage ─────────────────────────────────────────────
+
+describe("gateway routes to plugin handler", () => {
+  it("returns plugin result when handlePluginAction returns non-null", async () => {
+    const { handlePluginAction } = await import("../core/plugin.js");
+    (handlePluginAction as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      result: "from plugin",
+    });
+
+    gateway.setContext(123);
+    const { body } = await post({
+      action: "plugin_specific_action",
+      _chatId: "123",
+    });
+    expect(body.ok).toBe(true);
+    expect(body.result).toBe("from plugin");
+    gateway.clearContext(123);
+
+    // Restore to always-null for subsequent tests
+    (handlePluginAction as ReturnType<typeof vi.fn>).mockResolvedValue(null);
+  });
+});
+
+// ── Additional branch coverage ────────────────────────────────────────────
+
+describe("gateway — no frontend handler falls through to shared actions (line 162 FALSE branch)", () => {
+  it("routes to shared action when frontendHandler is null", async () => {
+    // Clear frontend handler — FALSE branch of `if (this.frontendHandler)`
+    gateway.setFrontendHandler(null);
+    gateway.setContext(123);
+
+    // read_history is a shared action that should still work
+    const { body } = await post({ action: "read_history", _chatId: "123" });
+    expect(body.ok).toBe(true);
+
+    gateway.clearContext(123);
+    gateway.setFrontendHandler(mockFrontendHandler); // restore
+  });
+});
+
+describe("gateway — non-Error thrown in handleAction catch (line 186 FALSE branch)", () => {
+  it("returns error with String(err) when handler throws a non-Error", async () => {
+    const stringThrowHandler = vi.fn(async () => {
+      throw "plain string gateway error";
+    });
+    gateway.setFrontendHandler(stringThrowHandler);
+    gateway.setContext(123);
+
+    const { body } = await post({
+      action: "send_message",
+      _chatId: "123",
+      text: "test",
+    });
+    expect(body.ok).toBe(false);
+    expect(String(body.error)).toContain("plain string gateway error");
+
+    gateway.clearContext(123);
+    gateway.setFrontendHandler(mockFrontendHandler); // restore
+  });
+});
+
+describe("gateway — start() called twice returns same port (line 195 TRUE branch)", () => {
+  it("returns port without restarting when already running", async () => {
+    // gateway is already started — calling start() again should return same port immediately
+    const secondPort = await gateway.start();
+    expect(secondPort).toBe(port);
+  });
+});
+
+describe("gateway health endpoint — old activity shows minutes ago (line 211 FALSE branch)", () => {
+  it("shows 'Xm ago' when msSinceLastMessage >= 60000", async () => {
+    const { getHealthStatus } = await import("../util/watchdog.js");
+    (getHealthStatus as ReturnType<typeof vi.fn>).mockReturnValueOnce({
+      healthy: true,
+      totalMessagesProcessed: 5,
+      recentErrorCount: 0,
+      msSinceLastMessage: 5 * 60_000, // 5 minutes ago → > 60000
+    });
+
+    const resp = await fetch(`http://127.0.0.1:${port}/health`);
+    const data = (await resp.json()) as Record<string, unknown>;
+    expect(data.lastActivity).toMatch(/m ago$/);
+  });
+});
+
+// ── Port retry (EADDRINUSE) ───────────────────────────────────────────────
+
+describe("gateway port retry — EADDRINUSE", () => {
+  it("rejects when all retry attempts are exhausted (6 consecutive ports in use)", async () => {
+    // The retry logic allows attempt 0-4 (5 retries), trying ports p, p+1, …, p+5
+    // Block all 6 consecutive ports so every attempt fails → should reject
+    const blockers: Array<import("node:http").Server> = [];
+    for (let p = 19950; p <= 19955; p++) {
+      const { createServer } = await import("node:http");
+      const s = createServer();
+      await new Promise<void>((resolve) => s.listen(p, "127.0.0.1", resolve));
+      blockers.push(s);
+    }
+
+    try {
+      const gw = new Gateway();
+      gw.setFrontendHandler(async () => null);
+      await expect(gw.start(19950)).rejects.toThrow();
+    } finally {
+      for (const s of blockers) {
+        await new Promise<void>((resolve) => s.close(() => resolve()));
+      }
+    }
+  });
+});

package/src/__tests__/gateway-retry.test.ts

@@ -0,0 +1,359 @@
+/**
+ * Tests for withRetry() exported from src/core/gateway.ts
+ *
+ * withRetry wraps p-retry.  We mock p-retry so that:
+ *   - The mock immediately drives the retry loop deterministically (no real
+ *     delays), and
+ *   - We can observe exactly how many times the inner function was called.
+ *
+ * The contract under test:
+ *   1. Success on first attempt — fn called once, result returned.
+ *   2. Retryable errors (network, overloaded, rate_limit) — fn retried up to
+ *      3 total attempts; result returned on the first successful call.
+ *   3. Non-retryable errors (auth, bad_request, context_length, forbidden,
+ *      unknown) — fn called once and the error is re-thrown immediately.
+ *   4. All retries exhausted — the final error is thrown after 3 attempts.
+ *   5. TalonError.retryAfterMs is plumbed through classify.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ── Mocks (before any dynamic import) ─────────────────────────────────────
+
+vi.mock("../util/log.js", () => ({
+  log: vi.fn(),
+  logError: vi.fn(),
+  logWarn: vi.fn(),
+  logDebug: vi.fn(),
+}));
+
+vi.mock("../core/dispatcher.js", () => ({
+  getActiveCount: vi.fn(() => 0),
+}));
+
+vi.mock("../util/watchdog.js", () => ({
+  getHealthStatus: vi.fn(() => ({
+    healthy: true,
+    totalMessagesProcessed: 0,
+    recentErrorCount: 0,
+    msSinceLastMessage: 0,
+  })),
+}));
+
+vi.mock("../storage/sessions.js", () => ({
+  getActiveSessionCount: vi.fn(() => 0),
+}));
+
+vi.mock("../core/gateway-actions.js", () => ({
+  handleSharedAction: vi.fn(async () => null),
+}));
+
+vi.mock("../core/plugin.js", () => ({
+  handlePluginAction: vi.fn(async () => null),
+}));
+
+vi.mock("node:fs", () => ({
+  existsSync: vi.fn(() => false),
+  readFileSync: vi.fn(() => "{}"),
+  mkdirSync: vi.fn(),
+  writeFileSync: vi.fn(),
+}));
+
+vi.mock("write-file-atomic", () => ({
+  default: { sync: vi.fn() },
+}));
+
+// ── Real p-retry (we want to exercise the actual retry logic with fast
+//    timeouts — no mocking needed since we use very short delays).
+//    We DO NOT mock p-retry; instead tests that would be slow use
+//    non-retryable errors so they return immediately, and retryable-path
+//    tests are designed to succeed on a subsequent attempt.
+
+// ── Dynamic import ─────────────────────────────────────────────────────────
+
+const { withRetry } = await import("../core/gateway.js");
+import { TalonError, classify } from "../core/errors.js";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+/** Build a TalonError for the given reason. */
+function talonErr(
+  reason:
+    | "network"
+    | "overloaded"
+    | "rate_limit"
+    | "auth"
+    | "bad_request"
+    | "context_length"
+    | "unknown",
+  retryAfterMs?: number,
+): TalonError {
+  const retryable = ["network", "overloaded", "rate_limit"].includes(reason);
+  return new TalonError(`${reason} error`, {
+    reason,
+    retryable,
+    retryAfterMs,
+  });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+describe("withRetry", () => {
+  describe("success on first attempt", () => {
+    it("returns the value without retrying", async () => {
+      const fn = vi.fn(async () => "ok");
+      const result = await withRetry(fn);
+      expect(result).toBe("ok");
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("returns non-string values correctly", async () => {
+      const obj = { data: 42, nested: { flag: true } };
+      const result = await withRetry(async () => obj);
+      expect(result).toBe(obj);
+    });
+
+    it("returns undefined correctly", async () => {
+      const result = await withRetry(async () => undefined);
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("non-retryable errors — abort immediately", () => {
+    it("throws on auth error without retrying", async () => {
+      const fn = vi.fn(async () => {
+        throw talonErr("auth");
+      });
+
+      await expect(withRetry(fn)).rejects.toThrow();
+      // Function should only be called once — no retries for non-retryable errors
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("throws on bad_request error without retrying", async () => {
+      const fn = vi.fn(async () => {
+        throw talonErr("bad_request");
+      });
+
+      await expect(withRetry(fn)).rejects.toThrow();
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("throws on context_length error without retrying", async () => {
+      const fn = vi.fn(async () => {
+        throw talonErr("context_length");
+      });
+
+      await expect(withRetry(fn)).rejects.toThrow();
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("throws on forbidden error without retrying", async () => {
+      const fn = vi.fn(async () => {
+        throw new TalonError("403 Forbidden", {
+          reason: "forbidden",
+          retryable: false,
+          status: 403,
+        });
+      });
+
+      await expect(withRetry(fn)).rejects.toThrow();
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("throws on unknown error without retrying", async () => {
+      const fn = vi.fn(async () => {
+        throw talonErr("unknown");
+      });
+
+      await expect(withRetry(fn)).rejects.toThrow();
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("re-classifies raw (non-TalonError) non-retryable errors and aborts", async () => {
+      // classify("401 Unauthorized") → auth → non-retryable
+      const fn = vi.fn(async () => {
+        throw new Error("401 Unauthorized");
+      });
+
+      await expect(withRetry(fn)).rejects.toThrow();
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("re-classifies 400 Bad Request as non-retryable", async () => {
+      const fn = vi.fn(async () => {
+        throw new Error("400 Bad Request");
+      });
+
+      await expect(withRetry(fn)).rejects.toThrow();
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("retryable errors — retries and eventually succeeds", () => {
+    it("succeeds on second attempt after a network error", async () => {
+      let calls = 0;
+      const fn = vi.fn(async () => {
+        calls++;
+        if (calls === 1) {
+          throw talonErr("network");
+        }
+        return "success";
+      });
+
+      const result = await withRetry(fn);
+      expect(result).toBe("success");
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    it("succeeds on third attempt after two overloaded errors", async () => {
+      let calls = 0;
+      const fn = vi.fn(async () => {
+        calls++;
+        if (calls < 3) {
+          throw talonErr("overloaded");
+        }
+        return "eventually ok";
+      });
+
+      const result = await withRetry(fn);
+      expect(result).toBe("eventually ok");
+      expect(fn).toHaveBeenCalledTimes(3);
+    });
+
+    it("succeeds on second attempt after a rate_limit error", async () => {
+      let calls = 0;
+      const fn = vi.fn(async () => {
+        calls++;
+        if (calls === 1) {
+          // Small retryAfterMs so the test runs fast
+          throw talonErr("rate_limit", 1);
+        }
+        return "rate limit passed";
+      });
+
+      const result = await withRetry(fn);
+      expect(result).toBe("rate limit passed");
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("exhausting all retries", () => {
+    it("throws the last error after 3 total attempts for retryable errors", async () => {
+      let calls = 0;
+      const networkErr = talonErr("network");
+      const fn = vi.fn(async () => {
+        calls++;
+        throw networkErr;
+      });
+
+      await expect(withRetry(fn)).rejects.toThrow();
+      // withRetry is configured with retries: 2 (3 total attempts)
+      expect(fn).toHaveBeenCalledTimes(3);
+    });
+
+    it("throws the last error after 3 total attempts for overloaded errors", async () => {
+      let calls = 0;
+      const fn = vi.fn(async () => {
+        calls++;
+        throw talonErr("overloaded");
+      });
+
+      await expect(withRetry(fn)).rejects.toThrow();
+      expect(fn).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("TalonError retryAfterMs is respected by classify", () => {
+    it("classify preserves retryAfterMs from rate-limit message", () => {
+      // Verify that classify() correctly parses the retryAfterMs so
+      // withRetry has accurate delay information.
+      const err = classify(new Error("rate limit hit, retry after 45 seconds"));
+      expect(err.reason).toBe("rate_limit");
+      expect(err.retryAfterMs).toBe(45_000);
+    });
+
+    it("classify defaults retryAfterMs to 60000 when no retry hint is given", () => {
+      const err = classify(new Error("rate limit exceeded"));
+      expect(err.retryAfterMs).toBe(60_000);
+    });
+
+    it("classify caps retryAfterMs at 300000", () => {
+      const err = classify(new Error("rate limit, retry after 9999 seconds"));
+      expect(err.retryAfterMs).toBe(300_000);
+    });
+
+    it("network errors have retryAfterMs of 2000", () => {
+      const err = classify(new Error("ECONNREFUSED"));
+      expect(err.retryAfterMs).toBe(2_000);
+    });
+
+    it("overloaded errors have retryAfterMs of 5000 when matched via keyword", () => {
+      const err = classify(new Error("server is overloaded"));
+      expect(err.retryAfterMs).toBe(5_000);
+    });
+
+    it("5xx server errors have retryAfterMs of 2000", () => {
+      const err = classify(new Error("500 Internal Server Error"));
+      expect(err.retryAfterMs).toBe(2_000);
+    });
+  });
+
+  describe("error identity through withRetry", () => {
+    it("non-retryable TalonError reason is preserved in thrown error", async () => {
+      const original = talonErr("auth");
+      await expect(
+        withRetry(async () => {
+          throw original;
+        }),
+      ).rejects.toMatchObject({ reason: "auth" });
+    });
+
+    it("after exhausted retries the thrown error is a TalonError", async () => {
+      await expect(
+        withRetry(async () => {
+          throw talonErr("network");
+        }),
+      ).rejects.toBeInstanceOf(TalonError);
+    });
+
+    it("non-Error throws are classified and the TalonError is thrown for non-retryable", async () => {
+      await expect(
+        withRetry(async () => {
+          // eslint-disable-next-line @typescript-eslint/only-throw-error
+          throw 42; // will be classified as "unknown" (non-retryable)
+        }),
+      ).rejects.toBeInstanceOf(TalonError);
+    });
+  });
+
+  describe("concurrency — multiple independent withRetry calls", () => {
+    it("two simultaneous calls both succeed independently", async () => {
+      const [r1, r2] = await Promise.all([
+        withRetry(async () => "first"),
+        withRetry(async () => "second"),
+      ]);
+      expect(r1).toBe("first");
+      expect(r2).toBe("second");
+    });
+
+    it("one failing call does not affect a parallel successful call", async () => {
+      const results = await Promise.allSettled([
+        withRetry(async () => {
+          throw talonErr("auth"); // aborts immediately, non-retryable
+        }),
+        withRetry(async () => "safe"),
+      ]);
+
+      expect(results[0].status).toBe("rejected");
+      expect(results[1].status).toBe("fulfilled");
+      if (results[1].status === "fulfilled") {
+        expect(results[1].value).toBe("safe");
+      }
+    });
+  });
+});