talon-agent 1.0.0

package/src/__tests__/dispatcher.test.ts

@@ -0,0 +1,383 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { initDispatcher, execute, getActiveCount } from "../core/dispatcher.js";
+import type { QueryBackend, ContextManager } from "../core/types.js";
+
+function createMockDeps() {
+  const acquired: number[] = [];
+  const released: number[] = [];
+
+  const backend: QueryBackend = {
+    query: vi.fn(async () => ({
+      text: "response",
+      durationMs: 100,
+      inputTokens: 10,
+      outputTokens: 20,
+      cacheRead: 5,
+      cacheWrite: 3,
+    })),
+  };
+
+  const context: ContextManager = {
+    acquire: vi.fn((chatId: number) => { acquired.push(chatId); }),
+    release: vi.fn((chatId: number) => { released.push(chatId); }),
+    getMessageCount: vi.fn(() => 0),
+  };
+
+  const sendTyping = vi.fn(async () => {});
+  const onActivity = vi.fn();
+
+  return { backend, context, sendTyping, onActivity, acquired, released };
+}
+
+describe("dispatcher", () => {
+  beforeEach(() => {
+    const deps = createMockDeps();
+    initDispatcher(deps);
+  });
+
+  it("executes a query and returns result", async () => {
+    const result = await execute({
+      chatId: "123",
+      numericChatId: 123,
+      prompt: "hello",
+      senderName: "User",
+      isGroup: false,
+      source: "message",
+    });
+    expect(result.text).toBe("response");
+    expect(result.durationMs).toBe(100);
+    expect(result.bridgeMessageCount).toBe(0);
+  });
+
+  it("acquires and releases context", async () => {
+    const deps = createMockDeps();
+    initDispatcher(deps);
+
+    await execute({
+      chatId: "456",
+      numericChatId: 456,
+      prompt: "test",
+      senderName: "User",
+      isGroup: false,
+      source: "message",
+    });
+
+    expect(deps.context.acquire).toHaveBeenCalledWith(456, "456");
+    expect(deps.context.release).toHaveBeenCalledWith(456);
+  });
+
+  it("releases context even on error", async () => {
+    const deps = createMockDeps();
+    (deps.backend.query as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error("boom"),
+    );
+    initDispatcher(deps);
+
+    await expect(
+      execute({
+        chatId: "789",
+        numericChatId: 789,
+        prompt: "fail",
+        senderName: "User",
+        isGroup: false,
+        source: "message",
+      }),
+    ).rejects.toThrow("boom");
+
+    expect(deps.context.release).toHaveBeenCalledWith(789);
+  });
+
+  it("sends typing on execution", async () => {
+    const deps = createMockDeps();
+    initDispatcher(deps);
+
+    await execute({
+      chatId: "111",
+      numericChatId: 111,
+      prompt: "hi",
+      senderName: "User",
+      isGroup: false,
+      source: "message",
+    });
+
+    expect(deps.sendTyping).toHaveBeenCalledWith(111);
+  });
+
+  it("calls onActivity after successful query", async () => {
+    const deps = createMockDeps();
+    initDispatcher(deps);
+
+    await execute({
+      chatId: "222",
+      numericChatId: 222,
+      prompt: "hi",
+      senderName: "User",
+      isGroup: false,
+      source: "message",
+    });
+
+    expect(deps.onActivity).toHaveBeenCalled();
+  });
+
+  it("does not call onActivity on error", async () => {
+    const deps = createMockDeps();
+    (deps.backend.query as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error("fail"),
+    );
+    initDispatcher(deps);
+
+    await expect(
+      execute({
+        chatId: "333",
+        numericChatId: 333,
+        prompt: "fail",
+        senderName: "User",
+        isGroup: false,
+        source: "message",
+      }),
+    ).rejects.toThrow();
+
+    expect(deps.onActivity).not.toHaveBeenCalled();
+  });
+
+  it("passes stream callbacks to backend", async () => {
+    const deps = createMockDeps();
+    initDispatcher(deps);
+    const onStreamDelta = vi.fn();
+    const onTextBlock = vi.fn();
+
+    await execute({
+      chatId: "444",
+      numericChatId: 444,
+      prompt: "stream",
+      senderName: "User",
+      isGroup: false,
+      source: "message",
+      onStreamDelta,
+      onTextBlock,
+    });
+
+    expect(deps.backend.query).toHaveBeenCalledWith(
+      expect.objectContaining({ onStreamDelta, onTextBlock }),
+    );
+  });
+
+  it("tracks active count", async () => {
+    expect(getActiveCount()).toBe(0);
+
+    const deps = createMockDeps();
+    let resolveQuery!: () => void;
+    (deps.backend.query as ReturnType<typeof vi.fn>).mockImplementation(
+      () => new Promise<{ text: string; durationMs: number; inputTokens: number; outputTokens: number; cacheRead: number; cacheWrite: number }>((r) => {
+        resolveQuery = () => r({ text: "", durationMs: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0, cacheWrite: 0 });
+      }),
+    );
+    initDispatcher(deps);
+
+    const p = execute({ chatId: "555", numericChatId: 555, prompt: "hi", senderName: "U", isGroup: false, source: "message" });
+    // Give it a tick to start
+    await new Promise((r) => setTimeout(r, 10));
+    expect(getActiveCount()).toBe(1);
+
+    resolveQuery();
+    await p;
+    expect(getActiveCount()).toBe(0);
+  });
+
+  it("runs different-chat queries in true parallel", async () => {
+    const order: string[] = [];
+    const backend: QueryBackend = {
+      query: vi.fn(async (params) => {
+        order.push(`start:${params.chatId}`);
+        await new Promise((r) => setTimeout(r, 50));
+        order.push(`end:${params.chatId}`);
+        return { text: "", durationMs: 50, inputTokens: 0, outputTokens: 0, cacheRead: 0, cacheWrite: 0 };
+      }),
+    };
+
+    initDispatcher({
+      backend,
+      context: { acquire: () => {}, release: () => {}, getMessageCount: () => 0 },
+      sendTyping: async () => {},
+      onActivity: () => {},
+    });
+
+    // Fire two queries for DIFFERENT chats — they should overlap
+    await Promise.all([
+      execute({ chatId: "A", numericChatId: 1, prompt: "a", senderName: "U", isGroup: false, source: "message" }),
+      execute({ chatId: "B", numericChatId: 2, prompt: "b", senderName: "U", isGroup: false, source: "message" }),
+    ]);
+
+    // Both should START before either ENDS (true parallel)
+    expect(order[0]).toBe("start:A");
+    expect(order[1]).toBe("start:B");
+  });
+
+  it("second query still runs after first query errors (same chat)", async () => {
+    let callCount = 0;
+    const backend: QueryBackend = {
+      query: vi.fn(async () => {
+        callCount++;
+        if (callCount === 1) throw new Error("first fails");
+        return { text: "second ok", durationMs: 10, inputTokens: 0, outputTokens: 0, cacheRead: 0, cacheWrite: 0 };
+      }),
+    };
+
+    initDispatcher({
+      backend,
+      context: { acquire: () => {}, release: () => {}, getMessageCount: () => 0 },
+      sendTyping: async () => {},
+      onActivity: () => {},
+    });
+
+    const p1 = execute({ chatId: "ERR", numericChatId: 1, prompt: "fail", senderName: "U", isGroup: false, source: "message" });
+    const p2 = execute({ chatId: "ERR", numericChatId: 1, prompt: "succeed", senderName: "U", isGroup: false, source: "message" });
+
+    await expect(p1).rejects.toThrow("first fails");
+    const result = await p2;
+    expect(result.text).toBe("second ok");
+  });
+
+  it("activeCount is accurate during errors", async () => {
+    const backend: QueryBackend = {
+      query: vi.fn(async () => { throw new Error("boom"); }),
+    };
+
+    initDispatcher({
+      backend,
+      context: { acquire: () => {}, release: () => {}, getMessageCount: () => 0 },
+      sendTyping: async () => {},
+      onActivity: () => {},
+    });
+
+    await expect(
+      execute({ chatId: "X", numericChatId: 1, prompt: "x", senderName: "U", isGroup: false, source: "message" }),
+    ).rejects.toThrow("boom");
+
+    expect(getActiveCount()).toBe(0); // cleaned up even on error
+  });
+
+  it("cleans up chatChains after queries complete (no map leak)", async () => {
+    const backend: QueryBackend = {
+      query: vi.fn(async () => ({
+        text: "ok",
+        durationMs: 10,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+      })),
+    };
+
+    initDispatcher({
+      backend,
+      context: { acquire: () => {}, release: () => {}, getMessageCount: () => 0 },
+      sendTyping: async () => {},
+      onActivity: () => {},
+    });
+
+    // Execute queries for two different chats
+    await execute({
+      chatId: "cleanup-A",
+      numericChatId: 100,
+      prompt: "a",
+      senderName: "U",
+      isGroup: false,
+      source: "message",
+    });
+    await execute({
+      chatId: "cleanup-B",
+      numericChatId: 200,
+      prompt: "b",
+      senderName: "U",
+      isGroup: false,
+      source: "message",
+    });
+
+    // After both complete, activeCount should be 0 (chains cleaned up)
+    expect(getActiveCount()).toBe(0);
+
+    // Execute another query for the same chatId — should work fine (no stale chain)
+    const result = await execute({
+      chatId: "cleanup-A",
+      numericChatId: 100,
+      prompt: "c",
+      senderName: "U",
+      isGroup: false,
+      source: "message",
+    });
+    expect(result.text).toBe("ok");
+  });
+
+  it("calls sendTyping at least once during execution", async () => {
+    const deps = createMockDeps();
+    let resolveQuery!: () => void;
+    (deps.backend.query as ReturnType<typeof vi.fn>).mockImplementation(
+      () =>
+        new Promise<{
+          text: string;
+          durationMs: number;
+          inputTokens: number;
+          outputTokens: number;
+          cacheRead: number;
+          cacheWrite: number;
+        }>((r) => {
+          resolveQuery = () =>
+            r({
+              text: "done",
+              durationMs: 0,
+              inputTokens: 0,
+              outputTokens: 0,
+              cacheRead: 0,
+              cacheWrite: 0,
+            });
+        }),
+    );
+    initDispatcher(deps);
+
+    const p = execute({
+      chatId: "typing-test",
+      numericChatId: 777,
+      prompt: "hi",
+      senderName: "U",
+      isGroup: false,
+      source: "message",
+    });
+
+    // Wait for the initial sendTyping call
+    await new Promise((r) => setTimeout(r, 50));
+    expect(deps.sendTyping).toHaveBeenCalledWith(777);
+    expect(deps.sendTyping.mock.calls.length).toBeGreaterThanOrEqual(1);
+
+    resolveQuery();
+    await p;
+  });
+
+  it("serializes same-chat queries (FIFO)", async () => {
+    const order: string[] = [];
+    const backend: QueryBackend = {
+      query: vi.fn(async (params) => {
+        order.push(`start:${params.text}`);
+        await new Promise((r) => setTimeout(r, 30));
+        order.push(`end:${params.text}`);
+        return { text: "", durationMs: 30, inputTokens: 0, outputTokens: 0, cacheRead: 0, cacheWrite: 0 };
+      }),
+    };
+
+    initDispatcher({
+      backend,
+      context: { acquire: () => {}, release: () => {}, getMessageCount: () => 0 },
+      sendTyping: async () => {},
+      onActivity: () => {},
+    });
+
+    // Fire two queries for the SAME chat — second must wait
+    await Promise.all([
+      execute({ chatId: "X", numericChatId: 1, prompt: "first", senderName: "U", isGroup: false, source: "message" }),
+      execute({ chatId: "X", numericChatId: 1, prompt: "second", senderName: "U", isGroup: false, source: "message" }),
+    ]);
+
+    // Same chat: first completes before second starts
+    expect(order).toEqual(["start:first", "end:first", "start:second", "end:second"]);
+  });
+});

package/src/__tests__/errors.test.ts

@@ -0,0 +1,240 @@
+import { describe, it, expect } from "vitest";
+import { TalonError, classify, friendlyMessage } from "../core/errors.js";
+
+describe("classify", () => {
+  it("classifies rate limit errors", () => {
+    const err = classify(new Error("429 Too Many Requests"));
+    expect(err.reason).toBe("rate_limit");
+    expect(err.retryable).toBe(true);
+    expect(err.status).toBe(429);
+  });
+
+  it("extracts retry-after from rate limit", () => {
+    const err = classify(new Error("rate limit, retry after 30 seconds"));
+    expect(err.reason).toBe("rate_limit");
+    expect(err.retryAfterMs).toBe(30000);
+  });
+
+  it("classifies overloaded errors", () => {
+    const err = classify(new Error("503 Service Unavailable"));
+    expect(err.reason).toBe("overloaded");
+    expect(err.retryable).toBe(true);
+  });
+
+  it("classifies generic 5xx as overloaded", () => {
+    const err = classify(new Error("502 Bad Gateway"));
+    expect(err.reason).toBe("overloaded");
+    expect(err.retryable).toBe(true);
+  });
+
+  it("classifies network errors", () => {
+    expect(classify(new Error("ECONNREFUSED")).reason).toBe("network");
+    expect(classify(new Error("fetch failed")).reason).toBe("network");
+    expect(classify(new Error("ETIMEDOUT")).reason).toBe("network");
+    expect(classify(new Error("ENOTFOUND")).reason).toBe("network");
+  });
+
+  it("classifies session expired errors", () => {
+    const err = classify(new Error("session expired"));
+    expect(err.reason).toBe("session_expired");
+    expect(err.retryable).toBe(false);
+  });
+
+  it("classifies context length errors", () => {
+    const err = classify(new Error("context length exceeded"));
+    expect(err.reason).toBe("context_length");
+    expect(err.retryable).toBe(false);
+  });
+
+  it("classifies auth errors", () => {
+    const err = classify(new Error("401 Unauthorized"));
+    expect(err.reason).toBe("auth");
+    expect(err.retryable).toBe(false);
+  });
+
+  it("classifies 400 as bad_request", () => {
+    const err = classify(new Error("400 Bad Request"));
+    expect(err.reason).toBe("bad_request");
+    expect(err.retryable).toBe(false);
+  });
+
+  it("classifies 403 as forbidden", () => {
+    const err = classify(new Error("403 Forbidden"));
+    expect(err.reason).toBe("forbidden");
+    expect(err.retryable).toBe(false);
+  });
+
+  it("returns unknown for unrecognized errors", () => {
+    const err = classify(new Error("something weird"));
+    expect(err.reason).toBe("unknown");
+    expect(err.retryable).toBe(false);
+  });
+
+  it("passes through TalonError unchanged", () => {
+    const original = new TalonError("test", { reason: "rate_limit", retryable: true });
+    expect(classify(original)).toBe(original);
+  });
+
+  it("handles string errors", () => {
+    const err = classify("rate limit hit");
+    expect(err.reason).toBe("rate_limit");
+  });
+
+  it("handles non-Error objects", () => {
+    const err = classify(42);
+    expect(err.reason).toBe("unknown");
+  });
+
+  it("preserves original error as cause", () => {
+    const original = new Error("503 overloaded");
+    const err = classify(original);
+    expect(err.cause).toBe(original);
+  });
+
+  it("classifies 500 as retryable server error", () => {
+    const err = classify(new Error("500 Internal Server Error"));
+    expect(err.retryable).toBe(true);
+    expect(err.status).toBe(500);
+  });
+
+  it("classifies 504 as retryable", () => {
+    const err = classify(new Error("504 Gateway Timeout"));
+    expect(err.retryable).toBe(true);
+  });
+
+  it("classifies ENOTFOUND as network error", () => {
+    const err = classify(new Error("ENOTFOUND"));
+    expect(err.reason).toBe("network");
+    expect(err.retryable).toBe(true);
+  });
+
+  // Mutant killers: rate.?limit regex — .? allows optional char between rate and limit
+  it("matches 'rate limit' with space (rate.?limit regex)", () => {
+    const err = classify(new Error("rate limit exceeded"));
+    expect(err.reason).toBe("rate_limit");
+  });
+
+  it("matches 'ratelimit' without space (rate.?limit regex)", () => {
+    const err = classify(new Error("ratelimit exceeded"));
+    expect(err.reason).toBe("rate_limit");
+  });
+
+  // Mutant killers: retry.?after regex — .? allows optional char between retry and after
+  it("extracts retry-after with no separator (retryafter60)", () => {
+    const err = classify(new Error("ratelimit retryafter60"));
+    expect(err.reason).toBe("rate_limit");
+    expect(err.retryAfterMs).toBe(60_000);
+  });
+
+  it("extracts retry-after with hyphen separator (retry-after: 60)", () => {
+    const err = classify(new Error("rate limit hit, retry-after: 60"));
+    expect(err.reason).toBe("rate_limit");
+    expect(err.retryAfterMs).toBe(60_000);
+  });
+
+  // Mutant killers: status ?? 429 — default status when no status code in message
+  it("defaults to status 429 when rate limit message has no status code", () => {
+    const err = classify(new Error("rate limit exceeded, please slow down"));
+    expect(err.reason).toBe("rate_limit");
+    expect(err.status).toBe(429);
+  });
+
+  it("uses extracted status instead of 429 default when status present", () => {
+    // "503" would match overloaded first, so use a message that hits rate_limit with a non-429 status
+    const err = classify(new Error("rate limit hit, error 200 ok"));
+    expect(err.reason).toBe("rate_limit");
+    expect(err.status).toBe(200);
+  });
+
+  // Mutant killers: overloaded/503/capacity branch
+  it("classifies 'overloaded' keyword as overloaded", () => {
+    const err = classify(new Error("API is overloaded"));
+    expect(err.reason).toBe("overloaded");
+    expect(err.retryable).toBe(true);
+  });
+
+  it("classifies 'capacity' keyword as overloaded", () => {
+    const err = classify(new Error("at capacity, try again later"));
+    expect(err.reason).toBe("overloaded");
+    expect(err.retryable).toBe(true);
+  });
+
+  // Mutant killers: status ?? 503 for overloaded branch
+  it("defaults to status 503 when overloaded message has no status code", () => {
+    const err = classify(new Error("server is overloaded please wait"));
+    expect(err.reason).toBe("overloaded");
+    expect(err.status).toBe(503);
+  });
+
+  it("uses extracted status instead of 503 default for overloaded", () => {
+    // "503" is in the message so status would be 503 anyway — use a message with overloaded keyword + different status
+    const err = classify(new Error("overloaded, returned 502"));
+    expect(err.reason).toBe("overloaded");
+    expect(err.status).toBe(502);
+  });
+
+  // Mutant killers: context.*length regex — .* allows any chars between context and length
+  it("matches 'context length exceeded' (space between context and length)", () => {
+    const err = classify(new Error("context length exceeded"));
+    expect(err.reason).toBe("context_length");
+  });
+
+  it("matches 'context_length_exceeded' (underscore between context and length)", () => {
+    const err = classify(new Error("context_length_exceeded"));
+    expect(err.reason).toBe("context_length");
+  });
+});
+
+describe("friendlyMessage", () => {
+  it("returns rate limit message with retry time", () => {
+    const err = new TalonError("x", { reason: "rate_limit", retryAfterMs: 30000 });
+    expect(friendlyMessage(err)).toContain("30 seconds");
+  });
+
+  it("returns overloaded message", () => {
+    expect(friendlyMessage(new Error("503"))).toContain("busy");
+  });
+
+  it("returns network error message", () => {
+    expect(friendlyMessage(new Error("ECONNREFUSED"))).toContain("Connection");
+  });
+
+  it("returns context length message with /reset", () => {
+    const msg = friendlyMessage(new Error("context length exceeded"));
+    expect(msg).toContain("/reset");
+  });
+
+  it("passes through session expired messages as-is", () => {
+    const msg = "Session expired. Send your message again.";
+    const err = new TalonError(msg, { reason: "session_expired" });
+    expect(friendlyMessage(err)).toBe(msg);
+  });
+
+  it("classifies raw errors before generating message", () => {
+    expect(friendlyMessage(new Error("some random failure"))).toContain("Something went wrong");
+  });
+});
+
+describe("TalonError", () => {
+  it("is an instanceof Error", () => {
+    const err = new TalonError("test", { reason: "unknown" });
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(TalonError);
+  });
+
+  it("has correct name", () => {
+    const err = new TalonError("test", { reason: "rate_limit" });
+    expect(err.name).toBe("TalonError");
+  });
+
+  it("defaults retryable to false", () => {
+    const err = new TalonError("test", { reason: "unknown" });
+    expect(err.retryable).toBe(false);
+  });
+
+  it("preserves cause", () => {
+    const cause = new Error("original");
+    const err = new TalonError("wrapped", { reason: "unknown", cause });
+    expect(err.cause).toBe(cause);
+  });
+});