opc-agent 2.0.0 → 2.0.2

package/tests/agui-protocol.test.ts

@@ -0,0 +1,246 @@
+// AG-UI Protocol Tests
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  AGUIEventEmitter,
+  AGUIServer,
+  AGUIClient,
+  AGUI_EVENT_TYPES,
+  isValidEventType,
+} from '../src/protocols/agui';
+import type { AGUIEvent, AGUIRunRequest } from '../src/protocols/agui';
+
+// ─── Mock ServerResponse ─────────────────────────────────────
+
+function createMockRes() {
+  const chunks: string[] = [];
+  return {
+    chunks,
+    writeHead: vi.fn(),
+    write: vi.fn((data: string) => { chunks.push(data); return true; }),
+    end: vi.fn(),
+  };
+}
+
+function parseSSEChunks(chunks: string[]): AGUIEvent[] {
+  return chunks
+    .filter(c => c.startsWith('data: '))
+    .map(c => JSON.parse(c.slice(6).trim()));
+}
+
+// ─── Tests ───────────────────────────────────────────────────
+
+describe('AG-UI Protocol', () => {
+  describe('isValidEventType', () => {
+    it('should validate known event types', () => {
+      expect(isValidEventType('TEXT_MESSAGE_START')).toBe(true);
+      expect(isValidEventType('RUN_FINISHED')).toBe(true);
+      expect(isValidEventType('CUSTOM')).toBe(true);
+    });
+
+    it('should reject unknown event types', () => {
+      expect(isValidEventType('UNKNOWN')).toBe(false);
+      expect(isValidEventType('')).toBe(false);
+    });
+
+    it('should have all 15 event types', () => {
+      expect(AGUI_EVENT_TYPES.length).toBe(15);
+    });
+  });
+
+  describe('AGUIEventEmitter', () => {
+    let res: ReturnType<typeof createMockRes>;
+    let emitter: AGUIEventEmitter;
+
+    beforeEach(() => {
+      res = createMockRes();
+      emitter = new AGUIEventEmitter(res as any);
+    });
+
+    it('should emit SSE-formatted events', () => {
+      emitter.emit({ type: 'RUN_STARTED', runId: 'r1', timestamp: '2025-01-01T00:00:00Z' });
+      expect(res.chunks.length).toBe(1);
+      expect(res.chunks[0]).toMatch(/^data: \{.*\}\n\n$/);
+      const parsed = JSON.parse(res.chunks[0].slice(6));
+      expect(parsed.type).toBe('RUN_STARTED');
+      expect(parsed.runId).toBe('r1');
+    });
+
+    it('should emit textStart/textContent/textEnd flow', () => {
+      emitter.textStart('msg1');
+      emitter.textContent('msg1', 'Hello');
+      emitter.textContent('msg1', ' world');
+      emitter.textEnd('msg1');
+      const events = parseSSEChunks(res.chunks);
+      expect(events.length).toBe(4);
+      expect(events[0].type).toBe('TEXT_MESSAGE_START');
+      expect(events[0].messageId).toBe('msg1');
+      expect((events[0] as any).role).toBe('assistant');
+      expect(events[1].type).toBe('TEXT_MESSAGE_CONTENT');
+      expect((events[1] as any).delta).toBe('Hello');
+      expect(events[2].type).toBe('TEXT_MESSAGE_CONTENT');
+      expect((events[2] as any).delta).toBe(' world');
+      expect(events[3].type).toBe('TEXT_MESSAGE_END');
+    });
+
+    it('should emit tool call flow', () => {
+      emitter.toolCallStart('tc1', 'search');
+      emitter.toolCallArgs('tc1', '{"q":"test"}');
+      emitter.toolCallEnd('tc1');
+      const events = parseSSEChunks(res.chunks);
+      expect(events.length).toBe(3);
+      expect(events[0].type).toBe('TOOL_CALL_START');
+      expect((events[0] as any).toolCallName).toBe('search');
+      expect(events[1].type).toBe('TOOL_CALL_ARGS');
+      expect(events[2].type).toBe('TOOL_CALL_END');
+    });
+
+    it('should emit runStarted/runFinished', () => {
+      emitter.runStarted('r1', 'thread1');
+      emitter.runFinished('r1');
+      const events = parseSSEChunks(res.chunks);
+      expect(events[0].type).toBe('RUN_STARTED');
+      expect((events[0] as any).threadId).toBe('thread1');
+      expect(events[1].type).toBe('RUN_FINISHED');
+    });
+
+    it('should emit runError', () => {
+      emitter.runError('r1', 'Something went wrong', 'INTERNAL');
+      const events = parseSSEChunks(res.chunks);
+      expect(events[0].type).toBe('RUN_ERROR');
+      expect((events[0] as any).message).toBe('Something went wrong');
+      expect((events[0] as any).code).toBe('INTERNAL');
+    });
+
+    it('should emit stateSnapshot', () => {
+      emitter.stateSnapshot({ count: 42 });
+      const events = parseSSEChunks(res.chunks);
+      expect(events[0].type).toBe('STATE_SNAPSHOT');
+      expect((events[0] as any).snapshot.count).toBe(42);
+    });
+
+    it('should emit stateDelta', () => {
+      emitter.stateDelta([{ op: 'replace', path: '/count', value: 43 }]);
+      const events = parseSSEChunks(res.chunks);
+      expect(events[0].type).toBe('STATE_DELTA');
+      expect((events[0] as any).delta[0].op).toBe('replace');
+    });
+
+    it('should not emit after close', () => {
+      emitter.close();
+      emitter.textStart('msg1');
+      expect(res.chunks.length).toBe(0);
+      expect(res.end).toHaveBeenCalled();
+    });
+
+    it('should include timestamp on convenience methods', () => {
+      emitter.textStart('msg1');
+      const events = parseSSEChunks(res.chunks);
+      expect(events[0].timestamp).toBeDefined();
+      expect(typeof events[0].timestamp).toBe('string');
+    });
+
+    it('should emit step events', () => {
+      emitter.stepStarted('s1', 'process');
+      emitter.stepFinished('s1');
+      const events = parseSSEChunks(res.chunks);
+      expect(events[0].type).toBe('STEP_STARTED');
+      expect((events[0] as any).stepName).toBe('process');
+      expect(events[1].type).toBe('STEP_FINISHED');
+    });
+
+    it('should emit custom events', () => {
+      emitter.custom('my_event', { foo: 'bar' });
+      const events = parseSSEChunks(res.chunks);
+      expect(events[0].type).toBe('CUSTOM');
+      expect((events[0] as any).name).toBe('my_event');
+      expect((events[0] as any).value.foo).toBe('bar');
+    });
+
+    it('should emit messagesSnapshot', () => {
+      emitter.messagesSnapshot([{ id: 'm1', role: 'user', content: 'hi' }]);
+      const events = parseSSEChunks(res.chunks);
+      expect(events[0].type).toBe('MESSAGES_SNAPSHOT');
+      expect((events[0] as any).messages[0].content).toBe('hi');
+    });
+  });
+
+  describe('AGUIServer', () => {
+    it('should construct with default path', () => {
+      const mockAgent = { handleMessage: vi.fn(), handleMessageStream: vi.fn() };
+      const server = new AGUIServer(mockAgent as any);
+      expect(server).toBeDefined();
+    });
+
+    it('should handle run request with mock agent', async () => {
+      const mockAgent = {
+        handleMessage: vi.fn().mockResolvedValue({ content: 'Hello!' }),
+        handleMessageStream: async function* () { yield 'Hel'; yield 'lo!'; },
+      };
+      const server = new AGUIServer(mockAgent as any);
+      const res = createMockRes();
+
+      // Simulate request
+      const body = JSON.stringify({
+        messages: [{ id: 'msg1', role: 'user', content: 'Hi' }],
+      });
+      const req = {
+        [Symbol.asyncIterator]: async function* () { yield body; },
+      };
+
+      await server.handleRun(req as any, res as any);
+
+      expect(res.writeHead).toHaveBeenCalledWith(200, expect.objectContaining({
+        'Content-Type': 'text/event-stream',
+      }));
+
+      const events = parseSSEChunks(res.chunks);
+      const types = events.map(e => e.type);
+      expect(types).toContain('RUN_STARTED');
+      expect(types).toContain('TEXT_MESSAGE_START');
+      expect(types).toContain('TEXT_MESSAGE_CONTENT');
+      expect(types).toContain('TEXT_MESSAGE_END');
+      expect(types).toContain('RUN_FINISHED');
+    });
+
+    it('should return 400 for invalid JSON', async () => {
+      const mockAgent = { handleMessage: vi.fn() };
+      const server = new AGUIServer(mockAgent as any);
+      const res = createMockRes();
+      const req = { [Symbol.asyncIterator]: async function* () { yield 'not json'; } };
+
+      await server.handleRun(req as any, res as any);
+      expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+    });
+
+    it('should return 400 for missing messages', async () => {
+      const mockAgent = { handleMessage: vi.fn() };
+      const server = new AGUIServer(mockAgent as any);
+      const res = createMockRes();
+      const req = { [Symbol.asyncIterator]: async function* () { yield '{}'; } };
+
+      await server.handleRun(req as any, res as any);
+      expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+    });
+  });
+
+  describe('AGUIClient', () => {
+    it('should construct with endpoint', () => {
+      const client = new AGUIClient('http://localhost:3000/agui');
+      expect(client).toBeDefined();
+    });
+
+    it('should abort cleanly', () => {
+      const client = new AGUIClient('http://localhost:3000/agui');
+      // Should not throw when no active request
+      client.abort();
+    });
+  });
+
+  describe('Protocol list includes agui', () => {
+    it('should have agui in AGUI_EVENT_TYPES constants', () => {
+      expect(AGUI_EVENT_TYPES).toContain('TEXT_MESSAGE_START');
+      expect(AGUI_EVENT_TYPES).toContain('RUN_STARTED');
+      expect(AGUI_EVENT_TYPES).toContain('TOOL_CALL_START');
+    });
+  });
+});

package/tests/channels/discord.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi } from 'vitest';
+import { DiscordChannel } from '../../src/channels/discord';
+
+describe('DiscordChannel', () => {
+  it('constructor sets config from params', () => {
+    const ch = new DiscordChannel({ botToken: 'tok-123', applicationId: 'app-1' });
+    expect((ch as any).config.botToken).toBe('tok-123');
+    expect((ch as any).config.applicationId).toBe('app-1');
+  });
+
+  it('type is discord', () => {
+    const ch = new DiscordChannel({ botToken: 'tok' });
+    expect(ch.type).toBe('discord');
+  });
+
+  it('constructor reads token from env var', () => {
+    const orig = process.env.DISCORD_BOT_TOKEN;
+    process.env.DISCORD_BOT_TOKEN = 'env-discord-tok';
+    const ch = new DiscordChannel({});
+    expect((ch as any).config.botToken).toBe('env-discord-tok');
+    if (orig) process.env.DISCORD_BOT_TOKEN = orig;
+    else delete process.env.DISCORD_BOT_TOKEN;
+  });
+
+  it('defaults useThreads to true', () => {
+    const ch = new DiscordChannel({ botToken: 'tok' });
+    expect((ch as any).config.useThreads).toBe(true);
+  });
+
+  it('guildIds defaults to empty array', () => {
+    const ch = new DiscordChannel({ botToken: 'tok' });
+    expect((ch as any).config.guildIds).toEqual([]);
+  });
+
+  it('missing token results in empty string', () => {
+    const orig = process.env.DISCORD_BOT_TOKEN;
+    delete process.env.DISCORD_BOT_TOKEN;
+    const ch = new DiscordChannel({});
+    expect((ch as any).config.botToken).toBe('');
+    if (orig) process.env.DISCORD_BOT_TOKEN = orig;
+  });
+
+  it('start with no token warns but does not throw', async () => {
+    const orig = process.env.DISCORD_BOT_TOKEN;
+    delete process.env.DISCORD_BOT_TOKEN;
+    const ch = new DiscordChannel({});
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    await ch.start();
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+    if (orig) process.env.DISCORD_BOT_TOKEN = orig;
+  });
+
+  it('message chunking at 2000 chars', () => {
+    const longText = 'x'.repeat(3500);
+    const chunks: string[] = [];
+    for (let i = 0; i < longText.length; i += 2000) {
+      chunks.push(longText.slice(i, i + 2000));
+    }
+    expect(chunks).toHaveLength(2);
+    expect(chunks[0].length).toBe(2000);
+    expect(chunks[1].length).toBe(1500);
+  });
+
+  it('sequenceNumber starts null', () => {
+    const ch = new DiscordChannel({ botToken: 'tok' });
+    expect((ch as any).sequenceNumber).toBeNull();
+  });
+
+  it('ws starts null', () => {
+    const ch = new DiscordChannel({ botToken: 'tok' });
+    expect((ch as any).ws).toBeNull();
+  });
+
+  it('custom guildIds are set', () => {
+    const ch = new DiscordChannel({ botToken: 'tok', guildIds: ['g1', 'g2'] });
+    expect((ch as any).config.guildIds).toEqual(['g1', 'g2']);
+  });
+});

package/tests/channels/email.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { EmailChannel } from '../../src/channels/email';
+
+describe('EmailChannel', () => {
+  // ── Webhook Payload Parsing ──────────────────────
+
+  describe('parseWebhookPayload', () => {
+    it('should parse standard payload', () => {
+      const payload = {
+        from: 'alice@example.com',
+        to: ['bob@example.com'],
+        subject: 'Test Email',
+        body: 'Hello from email',
+        messageId: '<msg123@example.com>',
+        date: '2026-01-15T10:00:00Z',
+      };
+
+      const email = EmailChannel.parseWebhookPayload(payload);
+      expect(email).not.toBeNull();
+      expect(email!.from).toBe('alice@example.com');
+      expect(email!.to).toEqual(['bob@example.com']);
+      expect(email!.subject).toBe('Test Email');
+      expect(email!.body).toBe('Hello from email');
+      expect(email!.messageId).toBe('<msg123@example.com>');
+    });
+
+    it('should parse SendGrid-style payload', () => {
+      const payload = {
+        from: 'sender@test.com',
+        to: 'recipient@test.com',
+        subject: 'SG Test',
+        text: 'Body from SendGrid',
+        html: '<p>Body from SendGrid</p>',
+      };
+
+      const email = EmailChannel.parseWebhookPayload(payload);
+      expect(email).not.toBeNull();
+      expect(email!.body).toBe('Body from SendGrid');
+      expect(email!.html).toBe('<p>Body from SendGrid</p>');
+      expect(email!.to).toEqual(['recipient@test.com']);
+    });
+
+    it('should parse Mailgun-style payload', () => {
+      const payload = {
+        sender: 'mg@example.com',
+        recipient: 'user@example.com',
+        subject: 'MG Test',
+        'body-plain': 'Plain text body',
+        'body-html': '<p>HTML body</p>',
+        'Message-Id': '<mg123@mailgun>',
+      };
+
+      const email = EmailChannel.parseWebhookPayload(payload);
+      expect(email).not.toBeNull();
+      expect(email!.from).toBe('mg@example.com');
+      expect(email!.body).toBe('Plain text body');
+      expect(email!.messageId).toBe('<mg123@mailgun>');
+    });
+
+    it('should return null for payload without from', () => {
+      const email = EmailChannel.parseWebhookPayload({ subject: 'No sender' });
+      expect(email).toBeNull();
+    });
+
+    it('should handle envelope format', () => {
+      const payload = {
+        envelope: { from: 'env@test.com', to: ['a@b.com'] },
+        subject: 'Envelope test',
+        body: 'content',
+      };
+
+      const email = EmailChannel.parseWebhookPayload(payload);
+      expect(email).not.toBeNull();
+      expect(email!.from).toBe('env@test.com');
+    });
+
+    it('should generate messageId if missing', () => {
+      const payload = { from: 'a@b.com', body: 'test' };
+      const email = EmailChannel.parseWebhookPayload(payload);
+      expect(email).not.toBeNull();
+      expect(email!.messageId).toMatch(/^email-/);
+    });
+
+    it('should handle inReplyTo and references', () => {
+      const payload = {
+        from: 'a@b.com',
+        body: 'reply',
+        inReplyTo: '<orig@b.com>',
+        references: ['<orig@b.com>', '<prev@b.com>'],
+      };
+
+      const email = EmailChannel.parseWebhookPayload(payload);
+      expect(email!.inReplyTo).toBe('<orig@b.com>');
+      expect(email!.references).toEqual(['<orig@b.com>', '<prev@b.com>']);
+    });
+  });
+
+  // ── Filter Matching ──────────────────────────────
+
+  describe('matchesFilters', () => {
+    it('should match all when no filters', () => {
+      const channel = new EmailChannel({ mode: 'webhook' });
+      const result = channel.matchesFilters({
+        messageId: 'x', from: 'a@b.com', to: [], subject: 'test', body: '', date: new Date(),
+      });
+      expect(result).toBe(true);
+    });
+
+    it('should filter by from address', () => {
+      const channel = new EmailChannel({
+        mode: 'webhook',
+        filters: { from: ['allowed@example.com'] },
+      });
+
+      expect(channel.matchesFilters({
+        messageId: 'x', from: 'allowed@example.com', to: [], subject: '', body: '', date: new Date(),
+      })).toBe(true);
+
+      expect(channel.matchesFilters({
+        messageId: 'x', from: 'blocked@other.com', to: [], subject: '', body: '', date: new Date(),
+      })).toBe(false);
+    });
+
+    it('should filter by subject', () => {
+      const channel = new EmailChannel({
+        mode: 'webhook',
+        filters: { subject: ['[SUPPORT]'] },
+      });
+
+      expect(channel.matchesFilters({
+        messageId: 'x', from: 'a@b.com', to: [], subject: '[SUPPORT] Help me', body: '', date: new Date(),
+      })).toBe(true);
+
+      expect(channel.matchesFilters({
+        messageId: 'x', from: 'a@b.com', to: [], subject: 'Random email', body: '', date: new Date(),
+      })).toBe(false);
+    });
+  });
+
+  // ── Constructor ──────────────────────────────────
+
+  describe('constructor', () => {
+    it('should create with webhook mode', () => {
+      const channel = new EmailChannel({ mode: 'webhook', webhookPort: 9090 });
+      expect(channel.type).toBe('email');
+    });
+  });
+});

package/tests/channels/feishu.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect } from 'vitest';
+import { FeishuChannel } from '../../src/channels/feishu';
+
+describe('FeishuChannel', () => {
+  // ── Event Parsing ────────────────────────────────
+
+  describe('parseEventBody', () => {
+    it('should parse url_verification challenge', () => {
+      const body = { type: 'url_verification', challenge: 'abc123' };
+      const result = FeishuChannel.parseEventBody(body);
+      expect(result.type).toBe('url_verification');
+      expect(result.challenge).toBe('abc123');
+    });
+
+    it('should parse text message event', () => {
+      const body = {
+        header: {
+          event_id: 'evt_123',
+          event_type: 'im.message.receive_v1',
+          token: 'tok',
+        },
+        event: {
+          message: {
+            message_id: 'msg_123',
+            chat_id: 'oc_456',
+            message_type: 'text',
+            content: JSON.stringify({ text: 'Hello Feishu' }),
+            create_time: '1699999999',
+            chat_type: 'p2p',
+          },
+          sender: {
+            sender_id: { open_id: 'ou_789' },
+          },
+        },
+      };
+
+      const result = FeishuChannel.parseEventBody(body);
+      expect(result.type).toBe('message');
+      expect(result.content).toBe('Hello Feishu');
+      expect(result.chatId).toBe('oc_456');
+      expect(result.senderId).toBe('ou_789');
+      expect(result.messageId).toBe('msg_123');
+    });
+
+    it('should strip @bot mentions from content', () => {
+      const body = {
+        header: { event_type: 'im.message.receive_v1' },
+        event: {
+          message: {
+            message_id: 'msg_1',
+            chat_id: 'oc_1',
+            message_type: 'text',
+            content: JSON.stringify({ text: '@_user_123 Hello bot' }),
+          },
+          sender: { sender_id: { open_id: 'ou_1' } },
+        },
+      };
+
+      const result = FeishuChannel.parseEventBody(body);
+      expect(result.content).toBe('Hello bot');
+    });
+
+    it('should return empty content for non-text messages', () => {
+      const body = {
+        header: { event_type: 'im.message.receive_v1' },
+        event: {
+          message: {
+            message_id: 'msg_1',
+            chat_id: 'oc_1',
+            message_type: 'image',
+            content: '{}',
+          },
+          sender: { sender_id: { open_id: 'ou_1' } },
+        },
+      };
+
+      const result = FeishuChannel.parseEventBody(body);
+      expect(result.content).toBe('');
+    });
+
+    it('should handle unknown event types', () => {
+      const body = { header: { event_type: 'some.other.event' }, event: {} };
+      const result = FeishuChannel.parseEventBody(body);
+      expect(result.type).toBe('unknown');
+    });
+
+    it('should handle malformed content JSON gracefully', () => {
+      const body = {
+        header: { event_type: 'im.message.receive_v1' },
+        event: {
+          message: {
+            message_id: 'msg_1',
+            chat_id: 'oc_1',
+            message_type: 'text',
+            content: 'not-json',
+          },
+          sender: { sender_id: { open_id: 'ou_1' } },
+        },
+      };
+
+      const result = FeishuChannel.parseEventBody(body);
+      expect(result.content).toBe('not-json');
+    });
+  });
+
+  // ── Constructor ──────────────────────────────────
+
+  describe('constructor', () => {
+    it('should use defaults', () => {
+      const channel = new FeishuChannel();
+      expect(channel.type).toBe('feishu');
+    });
+
+    it('should accept config', () => {
+      const channel = new FeishuChannel({
+        appId: 'myapp',
+        appSecret: 'secret',
+        port: 9999,
+      });
+      expect(channel.type).toBe('feishu');
+    });
+  });
+});