@xalia/agent 0.5.7 → 0.6.0

package/src/chat/server/test-utils/mockFactories.ts

@@ -0,0 +1,422 @@
+/**
+ * Common mock factories for chat server tests
+ * Provides consistent mock objects across all test suites
+ */
+
+import { vi } from "vitest";
+import type { Database, UserData } from "../../data/database";
+import type { SessionData } from "../../data/dataModels";
+import type { ApiKeyManager } from "../../data/apiKeyManager";
+import type { OpenSession } from "../openSession";
+import type { WebSocket } from "ws";
+import type { AgentProfile } from "@xalia/xmcp/sdk";
+import type * as supabase from "../../../../../supabase/database.types";
+import { ClientToServer, ServerToClient } from "../../protocol/messages";
+import {
+  IMessageProcessor,
+  IUserConnectionManager,
+} from "../connectionManager";
+
+// =====================================
+// Mock Data Constants
+// =====================================
+
+export const MOCK_USERS = {
+  owner: {
+    uuid: "user-123",
+    nickname: "test-owner",
+  } as UserData,
+  participant: {
+    uuid: "user-456",
+    nickname: "test-participant",
+  } as UserData,
+  nonExistent: {
+    uuid: "user-999",
+    nickname: "non-existent",
+  } as UserData,
+};
+
+export const MOCK_SESSIONS = {
+  active: {
+    uuid: "session-abc",
+    title: "Test Session",
+    user_uuid: MOCK_USERS.owner.uuid,
+    agent_profile_uuid: "agent-profile-1",
+    workspace: null,
+    team_uuid: null,
+    public: false,
+    updated_at: "2025-01-01T00:00:00Z",
+  } as supabase.Tables<"sessions">,
+  secondary: {
+    uuid: "session-xyz",
+    title: "Secondary Session",
+    user_uuid: MOCK_USERS.owner.uuid,
+    agent_profile_uuid: "agent-profile-2",
+    workspace: null,
+    team_uuid: null,
+    public: false,
+    updated_at: "2025-01-01T01:00:00Z",
+  } as supabase.Tables<"sessions">,
+};
+
+export const MOCK_AGENT_PROFILES = {
+  default: {
+    system_prompt: "You are a helpful assistant",
+    model: "gpt-4",
+    mcp_settings: {},
+  } as AgentProfile,
+  custom: {
+    system_prompt: "You are a specialized assistant",
+    model: "claude-3",
+    mcp_settings: {
+      filesystem: ["read_file", "write_file"],
+    },
+  } as AgentProfile,
+};
+
+// =====================================
+// Mock Factory Functions
+// =====================================
+
+/**
+ * Creates a mock Database instance with common methods
+ */
+export function createMockDatabase(): {
+  mock: Database;
+  spies: {
+    sessionCreate: ReturnType<typeof vi.fn>;
+    sessionGetById: ReturnType<typeof vi.fn>;
+    getUserFromUuid: ReturnType<typeof vi.fn>;
+    getAgentProfileById: ReturnType<typeof vi.fn>;
+    getSavedAgentProfileById: ReturnType<typeof vi.fn>;
+    getUserApiKey: ReturnType<typeof vi.fn>;
+    sessionParticipantAdd: ReturnType<typeof vi.fn>;
+    sessionParticipantRemove: ReturnType<typeof vi.fn>;
+    updateAgentProfile: ReturnType<typeof vi.fn>;
+    sessionConversationAppend: ReturnType<typeof vi.fn>;
+    sessionGetParticipants: ReturnType<typeof vi.fn>;
+    getUserSessions: ReturnType<typeof vi.fn>;
+  };
+} {
+  const spies = {
+    sessionCreate: vi.fn(),
+    sessionGetById: vi.fn(),
+    getUserFromUuid: vi.fn(),
+    getAgentProfileById: vi.fn(),
+    getSavedAgentProfileById: vi.fn(),
+    getUserApiKey: vi.fn(),
+    sessionParticipantAdd: vi.fn(),
+    sessionParticipantRemove: vi.fn(),
+    updateAgentProfile: vi.fn(),
+    sessionConversationAppend: vi.fn(),
+    sessionGetParticipants: vi.fn(),
+    getUserSessions: vi.fn(),
+  };
+
+  const mock = {
+    ...spies,
+    // Add any other Database methods that might be called
+  } as unknown as Database;
+
+  return { mock, spies };
+}
+
+/**
+ * Creates a mock IUserConnectionManager instance
+ */
+export function createMockUserConnectionManager(): {
+  mock: IUserConnectionManager<ServerToClient>;
+  spies: {
+    sendToUsers: ReturnType<typeof vi.fn>;
+    getLiveUserApiKey: ReturnType<typeof vi.fn>;
+  };
+} {
+  const spies = {
+    sendToUsers: vi.fn(),
+    sendToConnection: vi.fn(),
+    sendServerError: vi.fn(),
+    getLiveUserApiKey: vi.fn(),
+  };
+
+  const mock = {
+    sendToUsers: spies.sendToUsers,
+    sendToConnection: spies.sendToConnection,
+    sendServerError: spies.sendServerError,
+    getLiveUserApiKey: spies.getLiveUserApiKey,
+  } as IUserConnectionManager<ServerToClient>;
+
+  return { mock, spies };
+}
+
+/**
+ * Creates a mock IMessageProcessor instance
+ */
+export function createMockSessionRegistry(): {
+  mock: IMessageProcessor<ClientToServer>;
+  spies: {
+    processMessage: ReturnType<typeof vi.fn>;
+    handleUserDisconnect: ReturnType<typeof vi.fn>;
+  };
+} {
+  const spies = {
+    processMessage: vi.fn(),
+    handleUserDisconnect: vi.fn(),
+  };
+
+  const mock = {
+    processMessage: spies.processMessage,
+    handleUserDisconnect: spies.handleUserDisconnect,
+  } as IMessageProcessor<ClientToServer>;
+
+  return { mock, spies };
+}
+
+/**
+ * Creates a mock ApiKeyManager instance
+ */
+export function createMockApiKeyManager(): {
+  mock: ApiKeyManager;
+  spies: {
+    verifyApiKey: ReturnType<typeof vi.fn>;
+  };
+} {
+  const spies = {
+    verifyApiKey: vi.fn(),
+  };
+
+  const mock = {
+    ...spies,
+  } as unknown as ApiKeyManager;
+
+  return { mock, spies };
+}
+
+/**
+ * Creates a mock WebSocket instance
+ */
+export function createMockWebSocket(readyState: number = 1): {
+  mock: WebSocket;
+  spies: {
+    on: ReturnType<typeof vi.fn>;
+    once: ReturnType<typeof vi.fn>;
+    send: ReturnType<typeof vi.fn>;
+    close: ReturnType<typeof vi.fn>;
+  };
+} {
+  const spies = {
+    on: vi.fn(),
+    once: vi.fn(),
+    send: vi.fn(),
+    close: vi.fn(),
+  };
+
+  const mock = {
+    ...spies,
+    readyState, // Allow setting initial readyState
+  } as unknown as WebSocket;
+
+  return { mock, spies };
+}
+
+/**
+ * Creates a mock OpenSession instance
+ */
+export function createMockOpenSession(sessionId = MOCK_SESSIONS.active.uuid): {
+  mock: OpenSession;
+  spies: {
+    addParticipant: ReturnType<typeof vi.fn>;
+    leave: ReturnType<typeof vi.fn>;
+    onClientMessage: ReturnType<typeof vi.fn>;
+    getSessionState: ReturnType<typeof vi.fn>;
+    broadcast: ReturnType<typeof vi.fn>;
+    sendTo: ReturnType<typeof vi.fn>;
+    onEmpty: ReturnType<typeof vi.fn>;
+  };
+} {
+  const spies = {
+    addParticipant: vi.fn(),
+    leave: vi.fn(),
+    onClientMessage: vi.fn(),
+    getSessionState: vi.fn(),
+    broadcast: vi.fn(),
+    sendTo: vi.fn(),
+    onEmpty: vi.fn(),
+  };
+
+  const mock = {
+    ...spies,
+    sessionUUID: sessionId,
+    users: new Set<string>(),
+    agentProfileUUID: MOCK_SESSIONS.active.agent_profile_uuid,
+    sessionOwnerUserUUID: MOCK_USERS.owner.uuid,
+  } as unknown as OpenSession;
+
+  return { mock, spies };
+}
+
+/**
+ * Creates a standard set of session list items for testing
+ */
+export function createMockSessionList(): Array<SessionData> {
+  return [
+    {
+      session_uuid: MOCK_SESSIONS.active.uuid,
+      title: MOCK_SESSIONS.active.title,
+      team_uuid: undefined,
+      agent_profile_uuid: MOCK_SESSIONS.active.agent_profile_uuid,
+      workspace: undefined,
+      updated_at: MOCK_SESSIONS.active.updated_at || "",
+      user_uuid: MOCK_SESSIONS.active.user_uuid,
+    },
+    {
+      session_uuid: MOCK_SESSIONS.secondary.uuid,
+      title: MOCK_SESSIONS.secondary.title,
+      team_uuid: undefined,
+      agent_profile_uuid: MOCK_SESSIONS.secondary.agent_profile_uuid,
+      workspace: undefined,
+      updated_at: MOCK_SESSIONS.secondary.updated_at || "",
+      user_uuid: MOCK_SESSIONS.secondary.user_uuid,
+    },
+  ];
+}
+
+/**
+ * Helper to setup common mock behaviors
+ */
+export function setupStandardMockBehaviors(mocks: {
+  database?: ReturnType<typeof createMockDatabase>;
+  apiKeyManager?: ReturnType<typeof createMockApiKeyManager>;
+  userConnectionManager?: ReturnType<typeof createMockUserConnectionManager>;
+}) {
+  // Setup database mocks
+  if (mocks.database) {
+    mocks.database.spies.getUserFromUuid.mockImplementation(
+      (userId: string) => {
+        if (userId === MOCK_USERS.owner.uuid)
+          return Promise.resolve(MOCK_USERS.owner);
+        if (userId === MOCK_USERS.participant.uuid)
+          return Promise.resolve(MOCK_USERS.participant);
+        return Promise.resolve(null);
+      }
+    );
+
+    mocks.database.spies.sessionGetById.mockImplementation(
+      (sessionId: string) => {
+        if (sessionId === MOCK_SESSIONS.active.uuid)
+          return Promise.resolve(MOCK_SESSIONS.active);
+        if (sessionId === MOCK_SESSIONS.secondary.uuid)
+          return Promise.resolve(MOCK_SESSIONS.secondary);
+        if (sessionId === "new-session-uuid")
+          return Promise.resolve({
+            ...MOCK_SESSIONS.active,
+            uuid: "new-session-uuid",
+          });
+        return Promise.resolve(null);
+      }
+    );
+
+    mocks.database.spies.getAgentProfileById.mockImplementation(
+      (profileId: string) => {
+        if (profileId === "agent-profile-1")
+          return Promise.resolve(MOCK_AGENT_PROFILES.default);
+        if (profileId === "agent-profile-2")
+          return Promise.resolve(MOCK_AGENT_PROFILES.custom);
+        return Promise.resolve(null);
+      }
+    );
+
+    mocks.database.spies.getSavedAgentProfileById.mockImplementation(
+      (profileId: string) => {
+        if (profileId === "agent-profile-1") {
+          return Promise.resolve({
+            uuid: "agent-profile-1",
+            user_uuid: MOCK_USERS.owner.uuid,
+            profile_name: "Default Profile",
+            profile: MOCK_AGENT_PROFILES.default,
+            preferences: { auto_approve: {} },
+          });
+        }
+        if (profileId === "agent-profile-2") {
+          return Promise.resolve({
+            uuid: "agent-profile-2",
+            user_uuid: MOCK_USERS.owner.uuid,
+            profile_name: "Custom Profile",
+            profile: MOCK_AGENT_PROFILES.custom,
+            preferences: { auto_approve: {} },
+          });
+        }
+        return Promise.resolve(null);
+      }
+    );
+
+    mocks.database.spies.getUserApiKey.mockImplementation((userId: string) => {
+      if (userId === MOCK_USERS.owner.uuid) {
+        return Promise.resolve("valid-api-key");
+      }
+      if (userId === MOCK_USERS.participant.uuid) {
+        return Promise.resolve("participant-api-key");
+      }
+      return Promise.resolve(undefined);
+    });
+
+    mocks.database.spies.sessionCreate.mockImplementation(() =>
+      Promise.resolve()
+    );
+
+    mocks.database.spies.sessionParticipantAdd.mockImplementation(() =>
+      Promise.resolve()
+    );
+
+    mocks.database.spies.sessionParticipantRemove.mockImplementation(() =>
+      Promise.resolve()
+    );
+
+    // Setup sessionGetParticipants to return participants based on session
+    mocks.database.spies.sessionGetParticipants.mockImplementation(
+      (sessionId: string) => {
+        if (sessionId === MOCK_SESSIONS.active.uuid) {
+          return Promise.resolve([
+            { user_uuid: MOCK_USERS.owner.uuid, role: "owner" },
+            { user_uuid: MOCK_USERS.participant.uuid, role: "participant" },
+          ]);
+        }
+        if (sessionId === MOCK_SESSIONS.secondary.uuid) {
+          return Promise.resolve([
+            { user_uuid: MOCK_USERS.owner.uuid, role: "owner" },
+          ]);
+        }
+        return Promise.resolve([]);
+      }
+    );
+
+    // Setup getUserSessions to return empty array by default
+    mocks.database.spies.getUserSessions.mockImplementation(() =>
+      Promise.resolve([])
+    );
+  }
+
+  // Setup API key manager mocks
+  if (mocks.apiKeyManager) {
+    mocks.apiKeyManager.spies.verifyApiKey.mockImplementation(
+      (apiKey: string) => {
+        if (apiKey === "valid-api-key")
+          return Promise.resolve(MOCK_USERS.owner);
+        if (apiKey === "participant-api-key")
+          return Promise.resolve(MOCK_USERS.participant);
+        return Promise.resolve(null);
+      }
+    );
+  }
+
+  // Setup user connection manager mocks
+  if (mocks.userConnectionManager) {
+    mocks.userConnectionManager.spies.getLiveUserApiKey.mockImplementation(
+      (userId: string) => {
+        if (userId === MOCK_USERS.owner.uuid) return "valid-api-key";
+        if (userId === MOCK_USERS.participant.uuid)
+          return "participant-api-key";
+        return undefined;
+      }
+    );
+  }
+}

package/src/chat/server/tools.ts

@@ -0,0 +1,265 @@
+/**
+ * Collection of simple Agent tools.
+ */
+
+import { OpenAI } from "openai";
+import { Parser } from "expr-eval";
+
+import { Agent, IAgentToolProvider, ToolCallResult } from "../../agent/agent";
+import { IPlatform } from "../../agent/iplatform";
+import { htmlToText } from "../utils/htmlToText";
+import { getLogger } from "@xalia/xmcp/sdk";
+import { webSearch } from "../utils/search";
+
+const logger = getLogger();
+
+/**
+ * Returns a function which parses an `args` struct and attempts to extract
+ * multiple string parameters with the given names.  e.g.
+ *
+ *   const parseFn = makeParseArgsFn(["arg0", "arg1"] as const)
+ *
+ * creates `parseFn: (args: unknown) => { arg0: string, arg1: string }` which
+ * can be used to parse tool arguments.
+ *
+ * NOTE, the complex type parameters ensures that the name list is a
+ * compile-time value, which in turn ensures that the return value of this
+ * function is well-typed.
+ */
+export function makeParseArgsFn<
+  T extends readonly string[] & (string extends T[number] ? never : unknown),
+>(names: T): (args: unknown) => { [K in T[number]]: string } {
+  return (args: unknown) => {
+    if (typeof args !== "object") {
+      throw new Error(`invalid args: ${typeof args}`);
+    }
+    const argsObj = args as Record<string, string>;
+    for (const name of names) {
+      const val = argsObj[name];
+      if (typeof val !== "string") {
+        throw new Error(`invalid expr args.${name}: ${typeof val}`);
+      }
+    }
+    return argsObj as { [K in T[number]]: string };
+  };
+}
+
+const DATETIME_DESC: OpenAI.ChatCompletionTool = {
+  type: "function",
+  function: {
+    name: "time_now",
+    description: "Current time",
+  },
+};
+
+export function isoWithTimezone(timeZone: string): string {
+  return (
+    new Intl.DateTimeFormat("sv-SE", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false,
+      timeZoneName: "short",
+    })
+      .format(new Date())
+      .replace(" ", "T") + ` (${timeZone})`
+  );
+}
+
+export function datetimeTool(timezone: string): IAgentToolProvider {
+  // eslint-disable-next-line @typescript-eslint/require-await
+  const toolFn = async () => {
+    return { response: isoWithTimezone(timezone) };
+  };
+  return {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    setup: async (agent: Agent) => {
+      agent.addAgentTool(DATETIME_DESC, toolFn);
+    },
+  };
+}
+
+const ARITHMETIC_DESC: OpenAI.ChatCompletionTool = {
+  type: "function",
+  function: {
+    name: "arithmetic",
+    description: "Evaluate arithmetic expression",
+    parameters: {
+      type: "object",
+      properties: {
+        expr: {
+          type: "string",
+          description: "Expression containing +-*/()",
+        },
+      },
+      required: ["expr"],
+    },
+  },
+};
+
+export function calculatorEval(args: string): string {
+  try {
+    return String(Parser.evaluate(args));
+  } catch (e) {
+    if (typeof (e as { message: string }).message === "string") {
+      return (e as { message: string }).message;
+    }
+    return String(e);
+  }
+}
+
+export const calculatorTool: IAgentToolProvider = {
+  // eslint-disable-next-line @typescript-eslint/require-await
+  setup: async (agent: Agent) => {
+    const getExpr = makeParseArgsFn(["expr"] as const);
+    // eslint-disable-next-line @typescript-eslint/require-await
+    const toolFn = async (_: Agent, args: unknown): Promise<ToolCallResult> => {
+      const { expr } = getExpr(args);
+      return { response: calculatorEval(expr) };
+    };
+
+    agent.addAgentTool(ARITHMETIC_DESC, toolFn);
+  },
+};
+
+const RENDER_DESC: OpenAI.ChatCompletionTool = {
+  type: "function",
+  function: {
+    name: "render",
+    description: "Display the given html fragment inside a div element",
+    parameters: {
+      type: "object",
+      properties: {
+        html: {
+          type: "string",
+          description: "HTML fragment to render",
+        },
+      },
+      required: ["html"],
+    },
+  },
+};
+
+export function renderTool(platform: IPlatform): IAgentToolProvider {
+  const getHtml = makeParseArgsFn(["html"] as const);
+  const toolFn = async (_: Agent, args: unknown): Promise<ToolCallResult> => {
+    const { html } = getHtml(args);
+    await platform.renderHTML(html);
+    return { response: "" };
+  };
+
+  return {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    setup: async (agent: Agent) => {
+      agent.addAgentTool(RENDER_DESC, toolFn);
+    },
+  };
+}
+
+const WEB_SEARCH_DESC: OpenAI.ChatCompletionTool = {
+  type: "function",
+  function: {
+    name: "web_search",
+    description: "Web search",
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query text",
+        },
+      },
+      required: ["query"],
+    },
+  },
+};
+
+export function webSearchTool(): IAgentToolProvider {
+  const getQuery = makeParseArgsFn(["query"] as const);
+  const toolFn = async (_: Agent, args: unknown): Promise<ToolCallResult> => {
+    const { query } = getQuery(args);
+    logger.debug(`[web_search]: query: ${query}`);
+    const results = await webSearch(query);
+    logger.debug(`[web_search]: results: ${results}`);
+    return { response: JSON.stringify(results) };
+  };
+
+  return {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    setup: async (agent: Agent) => {
+      agent.addAgentTool(WEB_SEARCH_DESC, toolFn);
+    },
+  };
+}
+
+// open_url
+
+/**
+ * For now, this matches the duckduckgo-mcp-server length.  Could extend
+ * depending on the application / model etc.
+ */
+const _OPEN_URL_MAX_LENGTH_STR = process.env["OPEN_URL_MAX_LENGTH"] || "8000";
+const OPEN_URL_MAX_LENGTH: number = parseInt(_OPEN_URL_MAX_LENGTH_STR, 10);
+
+const OPEN_URL_DESC: OpenAI.ChatCompletionTool = {
+  type: "function",
+  function: {
+    name: "open_url",
+    description: "Download content from a URL",
+    parameters: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "URL to download",
+        },
+      },
+      required: ["url"],
+    },
+  },
+};
+
+export async function openURL(url: string): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    const status = String(response.status);
+    const code = response.statusText;
+    throw new Error(`Failed to fetch ${url}: ${status} ${code}`);
+  }
+  const html = await response.text();
+  return htmlToText(html, OPEN_URL_MAX_LENGTH);
+}
+
+export function openURLTool(): IAgentToolProvider {
+  const getURL = makeParseArgsFn(["url"] as const);
+  const toolFn = async (_: Agent, args: unknown): Promise<ToolCallResult> => {
+    const { url } = getURL(args);
+    return { response: await openURL(url) };
+  };
+
+  return {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    setup: async (agent: Agent) => {
+      agent.addAgentTool(OPEN_URL_DESC, toolFn);
+    },
+  };
+}
+
+/**
+ * Add a set of agent tools for chat sessions.
+ */
+export async function addDefaultChatTools(
+  agent: Agent,
+  timezone: string,
+  platform: IPlatform
+): Promise<void> {
+  await agent.addAgentToolProvider(datetimeTool(timezone));
+  await agent.addAgentToolProvider(calculatorTool);
+  await agent.addAgentToolProvider(renderTool(platform));
+  await agent.addAgentToolProvider(webSearchTool());
+  await agent.addAgentToolProvider(openURLTool());
+}