@multiplayer-app/ai-agent-node 0.0.1

package/dist/tools/proposeFormValuesTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposeFormValuesTool.d.ts","sourceRoot":"","sources":["../../src/tools/proposeFormValuesTool.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,yBAAyB,wBAAwB,CAAA;AAE9D;;;GAGG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDpC,CAAA"}

package/dist/tools/proposeFormValuesTool.js

@@ -0,0 +1,56 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+export const proposeFormValuesToolName = 'propose_form_values';
+/**
+ * A no-side-effect tool: it exists to force the model to emit structured form fill proposals.
+ * The UI will render these proposals and the host app will decide what to apply.
+ */
+export const createProposeFormValuesTool = () => tool({
+    title: proposeFormValuesToolName,
+    description: 'Propose values to fill in a form. Use only allowed select options. Do not apply changes; just propose.',
+    inputSchema: z.object({
+        formId: z.string().min(1),
+        formName: z.string().min(1).optional(),
+        fields: z
+            .array(z.object({
+            name: z.string().min(1),
+            label: z.string().min(1),
+            value: z.string(),
+            inputType: z
+                .enum(['text', 'textarea', 'number', 'select', 'radio', 'checkbox', 'date', 'email', 'tel'])
+                .optional(),
+            options: z
+                .array(z.object({
+                value: z.string(),
+                label: z.string()
+            }))
+                .optional()
+        }))
+            .min(1),
+        notes: z.string().optional()
+    }),
+    outputSchema: z.object({
+        formId: z.string(),
+        formName: z.string().optional(),
+        fields: z.array(z.object({
+            name: z.string(),
+            label: z.string(),
+            value: z.string(),
+            inputType: z
+                .enum(['text', 'textarea', 'number', 'select', 'radio', 'checkbox', 'date', 'email', 'tel'])
+                .optional(),
+            options: z
+                .array(z.object({
+                value: z.string(),
+                label: z.string()
+            }))
+                .optional()
+        })),
+        notes: z.string().optional()
+    }),
+    execute: async (input) => {
+        // Preserve structured output. No I/O, no mutations.
+        return input;
+    }
+});
+//# sourceMappingURL=proposeFormValuesTool.js.map

package/dist/tools/proposeFormValuesTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposeFormValuesTool.js","sourceRoot":"","sources":["../../src/tools/proposeFormValuesTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AACzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAA;AAE9D;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,EAAE,CAC9C,IAAI,CAAC;IACH,KAAK,EAAE,yBAAyB;IAChC,WAAW,EACT,wGAAwG;IAC1G,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACzB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;QACtC,MAAM,EAAE,CAAC;aACN,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;YACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;YACjB,SAAS,EAAE,CAAC;iBACT,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;iBAC3F,QAAQ,EAAE;YACb,OAAO,EAAE,CAAC;iBACP,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;gBACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;gBACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;aAClB,CAAC,CACH;iBACA,QAAQ,EAAE;SACd,CAAC,CACH;aACA,GAAG,CAAC,CAAC,CAAC;QACT,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC7B,CAAC;IACF,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC;QACrB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,MAAM,EAAE,CAAC,CAAC,KAAK,CACb,CAAC,CAAC,MAAM,CAAC;YACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;YAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;YACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;YACjB,SAAS,EAAE,CAAC;iBACT,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;iBAC3F,QAAQ,EAAE;YACb,OAAO,EAAE,CAAC;iBACP,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;gBACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;gBACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;aAClB,CAAC,CACH;iBACA,QAAQ,EAAE;SACd,CAAC,CACH;QACD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC7B,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QACvB,oDAAoD;QACpD,OAAO,KAAK,CAAA;IACd,CAAC;CACF,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@multiplayer-app/ai-agent-node",
+  "version": "0.0.1",
+  "description": "AI Agent Node.js library for multiplayer ai agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "engines": {
+    "node": ">=18",
+    "npm": ">=8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "author": "Multiplayer",
+  "keywords": [
+    "ai-agent",
+    "library"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.9",
+    "@ai-sdk/google": "^3.0.6",
+    "@ai-sdk/openai": "^3.0.12",
+    "@multiplayer-app/ai-agent-db": "0.1.0",
+    "@multiplayer-app/ai-agent-types": "0.0.1",
+    "@openrouter/ai-sdk-provider": "^2.0.0",
+    "@socket.io/redis-adapter": "^8.3.0",
+    "ai": "6.0.3",
+    "dotenv": "^17.2.3",
+    "redis": "^5.10.0",
+    "socket.io": "^4.8.1",
+    "zod": "^4.2.1",
+    "kafkajs": "2.2.4",
+    "@aws-sdk/client-s3": "3.354.0",
+    "@aws-sdk/s3-request-presigner": "3.354.0",
+    "@aws-sdk/util-create-request": "3.347.0",
+    "@aws-sdk/util-format-url": "3.347.0",
+    "@aws-sdk/lib-storage": "3.354.0"
+  },
+  "peerDependencies": {
+    "mammoth": "^1.11.0",
+    "pdf-parse": "^2.4.5",
+    "ai": "^6.0.3"
+  },
+  "peerDependenciesMeta": {
+    "mammoth": {
+      "optional": true
+    },
+    "pdf-parse": {
+      "optional": true
+    },
+    "ai": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.16.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,46 @@
+import 'dotenv/config';
+
+/**
+ * Centralized configuration for the AI Agent Service
+ * All environment variables are accessed through this file
+ */
+
+export const config = {
+  // Redis configuration
+  redis: {
+    url: process.env.REDIS_URL,
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: Number(process.env.REDIS_PORT ?? 6379),
+    password: process.env.REDIS_PASSWORD,
+    database: process.env.REDIS_DATABASE ? Number(process.env.REDIS_DATABASE) : undefined,
+  },
+
+  // AI Provider API Keys
+  ai: {
+    openaiApiKey: process.env.OPENAI_API_KEY,
+    anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+    googleApiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
+    openrouterApiKey: process.env.OPENROUTER_API_KEY,
+    maxContextMessages: Number(process.env.MAX_CONTEXT_MESSAGES) || 10,
+    defaultModel: process.env.DEFAULT_MODEL,
+  },
+  s3: {
+    bucket: process.env.S3_ATTACHMENTS_BUCKET || 'ai-agent-attachments',
+  },
+  // Kafka configuration
+  kafka: {
+    groupId: process.env.KAFKA_GROUP_ID ?? 'ai-agent-node',
+    chatTitleGenerationTopic: process.env.KAFKA_CHAT_TITLE_GENERATION_TOPIC ?? 'chat-title-generation',
+    backgroundChatProcessingTopic: process.env.KAFKA_BACKGROUND_CHAT_PROCESSING_TOPIC ?? 'background-chat-processing',
+  },
+} as const;
+
+/**
+ * Get Redis connection URL
+ */
+export function getRedisUrl(): string {
+  if (config.redis.url) {
+    return config.redis.url;
+  }
+  return `redis://${config.redis.host}:${config.redis.port}`;
+}

package/src/helpers/AIHelper.test.ts

@@ -0,0 +1,375 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { AIHelper } from './AIHelper';
+import { ModelStore } from '../store/ModelStore';
+import { ConfigStore } from '../store/ConfigStore';
+import { MessageRole, AgentToolCallStatus } from '@multiplayer-app/ai-agent-types';
+import type { AgentMessage } from '@multiplayer-app/ai-agent-types';
+
+describe('AIHelper.getAssistantResponse', () => {
+  let modelStore: ModelStore;
+  let configStore: ConfigStore;
+
+  beforeAll(() => {
+    // Setup real ModelStore instance
+    modelStore = ModelStore.getInstance();
+    modelStore.setModels([
+      { id: 'openai/gpt-4o', label: 'GPT-4o Mini', provider: 'openrouter' }
+    ]);
+  });
+
+  describe('with tool approval responses', () => {
+    it('should handle approved tool with successful execution', async () => {
+      // Note: getAssistantResponse accepts Pick<AgentMessage, 'role' | 'content'>[]
+      // but convertMessages internally handles toolCalls, so we cast for testing
+      const messages = [
+        {
+          role: MessageRole.User,
+          content: 'Please execute the tool'
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'I will execute the tool for you.',
+          toolCalls: [
+            {
+              id: 'tool-call-1',
+              name: 'test-tool',
+              input: { param: 'value' },
+              status: AgentToolCallStatus.Succeeded,
+              approved: true,
+              output: { result: 'success', data: { executed: true } }
+            }
+          ]
+        }
+      ] as Pick<AgentMessage, 'role' | 'content' | 'toolCalls'>[];
+
+      const response = await AIHelper.getAssistantResponse(messages);
+
+      // Verify we get a response (actual model call)
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+
+      // The response should acknowledge the tool execution
+      // (exact text depends on model, so we just verify it's a valid response)
+    }, 30000);
+
+    it('should handle denied tool with execution-denied output', async () => {
+      const messages = [
+        {
+          role: MessageRole.User,
+          content: 'Please execute the tool'
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'I will execute the tool for you.',
+          toolCalls: [
+            {
+              id: 'tool-call-1',
+              name: 'test-tool',
+              input: { param: 'value' },
+              status: AgentToolCallStatus.Succeeded,
+              approved: false,
+              reason: 'User denied execution',
+              output: {
+                type: 'execution-denied',
+                reason: 'User denied execution'
+              }
+            }
+          ]
+        }
+      ] as Pick<AgentMessage, 'role' | 'content' | 'toolCalls'>[];
+
+      const response = await AIHelper.getAssistantResponse(messages);
+
+      // Verify we get a response acknowledging the denial
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+
+      // The model should respond to the execution-denied output
+    }, 30000);
+
+    it('should handle multiple tools with mixed approvals', async () => {
+      const messages = [
+        {
+          role: MessageRole.User,
+          content: 'Execute multiple tools'
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'I will execute the tools.',
+          toolCalls: [
+            {
+              id: 'tool-call-1',
+              name: 'approved-tool',
+              input: { param: 'value1' },
+              status: AgentToolCallStatus.Succeeded,
+              approved: true,
+              output: { result: 'approved-result' }
+            },
+            {
+              id: 'tool-call-2',
+              name: 'denied-tool',
+              input: { param: 'value2' },
+              status: AgentToolCallStatus.Succeeded,
+              approved: false,
+              reason: 'Not allowed',
+              output: {
+                type: 'execution-denied',
+                reason: 'Not allowed'
+              }
+            }
+          ]
+        }
+      ] as Pick<AgentMessage, 'role' | 'content' | 'toolCalls'>[];
+
+      const response = await AIHelper.getAssistantResponse(messages);
+
+      // Verify we get a response handling both tool results
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+
+      // The model should process both approved and denied tool results
+    }, 30000);
+
+    it('should handle tool execution failure', async () => {
+      const messages = [
+        {
+          role: MessageRole.User,
+          content: 'Execute the tool'
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'I will execute the tool.',
+          toolCalls: [
+            {
+              id: 'tool-call-1',
+              name: 'failing-tool',
+              input: { param: 'value' },
+              status: AgentToolCallStatus.Failed,
+              approved: true,
+              error: 'Tool execution failed: Network error'
+            }
+          ]
+        }
+      ] as Pick<AgentMessage, 'role' | 'content' | 'toolCalls'>[];
+
+      const response = await AIHelper.getAssistantResponse(messages);
+
+      // Verify we get a response even when tool execution failed
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+    }, 30000);
+
+    it('should handle tool with execution-denied due to tool not found', async () => {
+      const messages = [
+        {
+          role: MessageRole.User,
+          content: 'Execute the tool'
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'I will execute the tool.',
+          toolCalls: [
+            {
+              id: 'tool-call-1',
+              name: 'missing-tool',
+              input: { param: 'value' },
+              status: AgentToolCallStatus.Succeeded,
+              approved: true,
+              output: {
+                type: 'execution-denied',
+                reason: 'Tool was not found'
+              }
+            }
+          ]
+        }
+      ] as Pick<AgentMessage, 'role' | 'content' | 'toolCalls'>[];
+
+      const response = await AIHelper.getAssistantResponse(messages);
+
+      // Verify we get a response when tool was not found
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+    }, 30000);
+
+    it('should handle tool with execution-denied due to tool execution error', async () => {
+      const messages = [
+        {
+          role: MessageRole.User,
+          content: 'Execute the tool'
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'I will execute the tool.',
+          toolCalls: [
+            {
+              id: 'tool-call-1',
+              name: 'error-tool',
+              input: { param: 'value' },
+              status: AgentToolCallStatus.Succeeded,
+              approved: true,
+              output: {
+                type: 'execution-denied',
+                reason: 'Tool failed with error'
+              }
+            }
+          ]
+        }
+      ] as Pick<AgentMessage, 'role' | 'content' | 'toolCalls'>[];
+
+      const response = await AIHelper.getAssistantResponse(messages);
+
+      // Verify we get a response when tool execution had an error
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+    }, 30000);
+
+    it('should handle messages without tool calls', async () => {
+      const messages: Pick<AgentMessage, 'role' | 'content'>[] = [
+        {
+          role: MessageRole.User,
+          content: 'Hello, how are you?'
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'I am doing well, thank you!'
+        }
+      ];
+
+      const response = await AIHelper.getAssistantResponse(messages);
+
+      // Verify we get a response for normal conversation
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+    }, 30000);
+
+    it('should handle tool calls without output (pending approval)', async () => {
+      const messages = [
+        {
+          role: MessageRole.User,
+          content: 'Execute the tool'
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'I need to execute a tool.',
+          toolCalls: [
+            {
+              id: 'tool-call-1',
+              name: 'pending-tool',
+              input: { param: 'value' },
+              status: AgentToolCallStatus.Pending,
+              requiresConfirmation: true,
+              approvalId: 'approval-123'
+            }
+          ]
+        }
+      ] as Pick<AgentMessage, 'role' | 'content' | 'toolCalls'>[];
+
+      const response = await AIHelper.getAssistantResponse(messages);
+
+      // Verify we get a response even when tool is pending approval
+      // (tool calls without output should not include tool-result in messages)
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+    }, 30000);
+
+    it('should handle sequential tool approvals', async () => {
+      const messages = [
+        {
+          role: MessageRole.User,
+          content: 'First request'
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'Executing first tool.',
+          toolCalls: [
+            {
+              id: 'tool-call-1',
+              name: 'first-tool',
+              input: { step: 1 },
+              status: AgentToolCallStatus.Succeeded,
+              approved: true,
+              output: { result: 'first-result' }
+            }
+          ]
+        },
+        {
+          role: MessageRole.Assistant,
+          content: 'Now executing second tool.',
+          toolCalls: [
+            {
+              id: 'tool-call-2',
+              name: 'second-tool',
+              input: { step: 2 },
+              status: AgentToolCallStatus.Succeeded,
+              approved: false,
+              reason: 'User denied',
+              output: {
+                type: 'execution-denied',
+                reason: 'User denied'
+              }
+            }
+          ]
+        }
+      ] as Pick<AgentMessage, 'role' | 'content' | 'toolCalls'>[];
+
+      const response = await AIHelper.getAssistantResponse(messages);
+
+      // Verify we get a response for sequential tool calls
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+
+      // The model should process both sequential tool results
+    }, 30000);
+
+    it('should pass through options correctly', async () => {
+      const messages: Pick<AgentMessage, 'role' | 'content'>[] = [
+        {
+          role: MessageRole.User,
+          content: 'Test message'
+        }
+      ];
+
+      const response = await AIHelper.getAssistantResponse(messages, undefined, {
+        temperature: 0.9,
+        maxOutputTokens: 1000
+      });
+
+      // Verify we get a response with custom options applied
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+
+      // Options are passed through to the model
+    }, 30000);
+
+    it('should handle abort signal', async () => {
+      const messages: Pick<AgentMessage, 'role' | 'content'>[] = [
+        {
+          role: MessageRole.User,
+          content: 'Test message'
+        }
+      ];
+
+      const abortController = new AbortController();
+      const signal = abortController.signal;
+
+      const response = await AIHelper.getAssistantResponse(messages, signal);
+
+      // Verify we get a response with abort signal passed through
+      expect(response).toBeDefined();
+      expect(typeof response).toBe('string');
+      expect(response.length).toBeGreaterThan(0);
+
+      // Signal is passed through to the model for cancellation support
+    }, 30000);
+  });
+});