crewly 1.11.5 → 1.12.0

package/packages/crewly-agent/src/runtime/agent-stream.service.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Tests for AgentStreamService
+ *
+ * @module services/agent/crewly-agent/agent-stream.service.test
+ */
+
+import { describe, it, expect, beforeEach, vi, type Mocked, type MockInstance } from 'vitest';
+import {
+  AgentStreamService,
+  type AgentStreamEvent,
+  type TextChunkEvent,
+  type ToolCallStartEvent,
+  type ToolCallFinishEvent,
+  type StepFinishEvent,
+} from './agent-stream.service.js';
+
+describe('AgentStreamService', () => {
+  beforeEach(() => {
+    AgentStreamService.resetInstance();
+  });
+
+  it('should return the same singleton instance', () => {
+    const a = AgentStreamService.getInstance();
+    const b = AgentStreamService.getInstance();
+    expect(a).toBe(b);
+  });
+
+  it('should return a new instance after reset', () => {
+    const a = AgentStreamService.getInstance();
+    AgentStreamService.resetInstance();
+    const b = AgentStreamService.getInstance();
+    expect(a).not.toBe(b);
+  });
+
+  describe('emitTextChunk', () => {
+    it('should emit a text_chunk event with correct shape', () => {
+      const service = AgentStreamService.getInstance();
+      const handler = vi.fn();
+      service.on('stream', handler);
+
+      service.emitTextChunk('test-agent', 'Hello ');
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      const event = handler.mock.calls[0][0] as TextChunkEvent;
+      expect(event.type).toBe('text_chunk');
+      expect(event.sessionName).toBe('test-agent');
+      expect(event.text).toBe('Hello ');
+      expect(event.timestamp).toBeDefined();
+    });
+  });
+
+  describe('emitToolCallStart', () => {
+    it('should emit a tool_call_start event with args preview', () => {
+      const service = AgentStreamService.getInstance();
+      const handler = vi.fn();
+      service.on('stream', handler);
+
+      service.emitToolCallStart('test-agent', 'bash_exec', { command: 'ls -la' });
+
+      const event = handler.mock.calls[0][0] as ToolCallStartEvent;
+      expect(event.type).toBe('tool_call_start');
+      expect(event.toolName).toBe('bash_exec');
+      expect(event.argsPreview).toContain('ls -la');
+    });
+
+    it('should truncate long args to 200 chars', () => {
+      const service = AgentStreamService.getInstance();
+      const handler = vi.fn();
+      service.on('stream', handler);
+
+      const longArg = 'x'.repeat(300);
+      service.emitToolCallStart('test-agent', 'write_file', { content: longArg });
+
+      const event = handler.mock.calls[0][0] as ToolCallStartEvent;
+      expect(event.argsPreview.length).toBeLessThanOrEqual(200);
+    });
+  });
+
+  describe('emitToolCallFinish', () => {
+    it('should emit a tool_call_finish event with duration', () => {
+      const service = AgentStreamService.getInstance();
+      const handler = vi.fn();
+      service.on('stream', handler);
+
+      service.emitToolCallFinish('test-agent', 'bash_exec', { command: 'pwd' }, '/home/user', 42);
+
+      const event = handler.mock.calls[0][0] as ToolCallFinishEvent;
+      expect(event.type).toBe('tool_call_finish');
+      expect(event.toolName).toBe('bash_exec');
+      expect(event.resultPreview).toContain('/home/user');
+      expect(event.durationMs).toBe(42);
+    });
+
+    it('should handle null result gracefully', () => {
+      const service = AgentStreamService.getInstance();
+      const handler = vi.fn();
+      service.on('stream', handler);
+
+      service.emitToolCallFinish('test-agent', 'send_message', {}, null, 10);
+
+      const event = handler.mock.calls[0][0] as ToolCallFinishEvent;
+      expect(event.resultPreview).toBe('void');
+    });
+  });
+
+  describe('emitStepFinish', () => {
+    it('should emit a step_finish event', () => {
+      const service = AgentStreamService.getInstance();
+      const handler = vi.fn();
+      service.on('stream', handler);
+
+      service.emitStepFinish('test-agent', 3, true);
+
+      const event = handler.mock.calls[0][0] as StepFinishEvent;
+      expect(event.type).toBe('step_finish');
+      expect(event.stepIndex).toBe(3);
+      expect(event.hasToolCalls).toBe(true);
+    });
+  });
+
+  describe('multiple subscribers', () => {
+    it('should deliver events to all subscribers', () => {
+      const service = AgentStreamService.getInstance();
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+      service.on('stream', handler1);
+      service.on('stream', handler2);
+
+      service.emitTextChunk('test-agent', 'hello');
+
+      expect(handler1).toHaveBeenCalledTimes(1);
+      expect(handler2).toHaveBeenCalledTimes(1);
+    });
+
+    it('should filter by sessionName at subscriber level', () => {
+      const service = AgentStreamService.getInstance();
+      const agentAEvents: AgentStreamEvent[] = [];
+      const agentBEvents: AgentStreamEvent[] = [];
+
+      service.on('stream', (event: AgentStreamEvent) => {
+        if (event.sessionName === 'agent-a') agentAEvents.push(event);
+        if (event.sessionName === 'agent-b') agentBEvents.push(event);
+      });
+
+      service.emitTextChunk('agent-a', 'hello');
+      service.emitTextChunk('agent-b', 'world');
+      service.emitTextChunk('agent-a', '!');
+
+      expect(agentAEvents).toHaveLength(2);
+      expect(agentBEvents).toHaveLength(1);
+    });
+  });
+});

package/packages/crewly-agent/src/runtime/agent-stream.service.ts

@@ -0,0 +1,225 @@
+/**
+ * Agent Stream Service
+ *
+ * Singleton EventEmitter that broadcasts structured streaming events from
+ * in-process Crewly Agent runtimes. SSE endpoints subscribe to this service
+ * to forward real-time agent output to the frontend Dashboard.
+ *
+ * Event types:
+ * - text_chunk: Incremental text from the model
+ * - tool_call_start: A tool call has started executing
+ * - tool_call_finish: A tool call completed (with result and duration)
+ * - step_finish: A reasoning step completed
+ *
+ * @module services/agent/crewly-agent/agent-stream
+ */
+
+import { EventEmitter } from 'events';
+
+/**
+ * Streaming event types emitted to SSE clients
+ */
+export type StreamEventType =
+  | 'text_chunk'
+  | 'tool_call_start'
+  | 'tool_call_finish'
+  | 'step_finish'
+  | 'connected'
+  | 'heartbeat';
+
+/**
+ * Base shape for all stream events
+ */
+export interface StreamEvent {
+  /** Event type */
+  type: StreamEventType;
+  /** Agent session name */
+  sessionName: string;
+  /** ISO timestamp */
+  timestamp: string;
+}
+
+/**
+ * Text chunk event — incremental model output
+ */
+export interface TextChunkEvent extends StreamEvent {
+  type: 'text_chunk';
+  /** Text content */
+  text: string;
+}
+
+/**
+ * Tool call start event
+ */
+export interface ToolCallStartEvent extends StreamEvent {
+  type: 'tool_call_start';
+  /** Name of the tool being called */
+  toolName: string;
+  /** Arguments passed to the tool (serialized preview) */
+  argsPreview: string;
+}
+
+/**
+ * Tool call finish event
+ */
+export interface ToolCallFinishEvent extends StreamEvent {
+  type: 'tool_call_finish';
+  /** Name of the tool that completed */
+  toolName: string;
+  /** Arguments passed to the tool (serialized preview) */
+  argsPreview: string;
+  /** Result preview (truncated) */
+  resultPreview: string;
+  /** Execution duration in milliseconds */
+  durationMs: number;
+}
+
+/**
+ * Step finish event — a reasoning step completed
+ */
+export interface StepFinishEvent extends StreamEvent {
+  type: 'step_finish';
+  /** Step index (1-based) */
+  stepIndex: number;
+  /** Whether this step included tool calls */
+  hasToolCalls: boolean;
+}
+
+/**
+ * Union of all stream event types
+ */
+export type AgentStreamEvent =
+  | TextChunkEvent
+  | ToolCallStartEvent
+  | ToolCallFinishEvent
+  | StepFinishEvent;
+
+/** Maximum preview length for serialized args/results */
+const MAX_PREVIEW_LENGTH = 200;
+
+/**
+ * Singleton service that broadcasts agent streaming events.
+ *
+ * Runtime services call emit methods when streaming callbacks fire.
+ * SSE endpoints subscribe via the EventEmitter 'stream' event.
+ *
+ * @example
+ * ```typescript
+ * const streamService = AgentStreamService.getInstance();
+ *
+ * // Publish events (from runtime)
+ * streamService.emitTextChunk('my-agent', 'Hello ');
+ *
+ * // Subscribe (from SSE endpoint)
+ * streamService.on('stream', (event: AgentStreamEvent) => {
+ *   if (event.sessionName === targetSession) {
+ *     res.write(`data: ${JSON.stringify(event)}\n\n`);
+ *   }
+ * });
+ * ```
+ */
+export class AgentStreamService extends EventEmitter {
+  private static instance: AgentStreamService | null = null;
+
+  /**
+   * Get the singleton instance.
+   *
+   * @returns Shared AgentStreamService instance
+   */
+  static getInstance(): AgentStreamService {
+    if (!AgentStreamService.instance) {
+      AgentStreamService.instance = new AgentStreamService();
+    }
+    return AgentStreamService.instance;
+  }
+
+  /**
+   * Reset the singleton (for testing).
+   */
+  static resetInstance(): void {
+    if (AgentStreamService.instance) {
+      AgentStreamService.instance.removeAllListeners();
+    }
+    AgentStreamService.instance = null;
+  }
+
+  /**
+   * Emit a text chunk event.
+   *
+   * @param sessionName - Agent session name
+   * @param text - Text content
+   */
+  emitTextChunk(sessionName: string, text: string): void {
+    const event: TextChunkEvent = {
+      type: 'text_chunk',
+      sessionName,
+      timestamp: new Date().toISOString(),
+      text,
+    };
+    this.emit('stream', event);
+  }
+
+  /**
+   * Emit a tool call start event.
+   *
+   * @param sessionName - Agent session name
+   * @param toolName - Name of the tool
+   * @param args - Tool arguments
+   */
+  emitToolCallStart(sessionName: string, toolName: string, args: Record<string, unknown>): void {
+    const event: ToolCallStartEvent = {
+      type: 'tool_call_start',
+      sessionName,
+      timestamp: new Date().toISOString(),
+      toolName,
+      argsPreview: JSON.stringify(args).substring(0, MAX_PREVIEW_LENGTH),
+    };
+    this.emit('stream', event);
+  }
+
+  /**
+   * Emit a tool call finish event.
+   *
+   * @param sessionName - Agent session name
+   * @param toolName - Name of the tool
+   * @param args - Tool arguments
+   * @param result - Tool execution result
+   * @param durationMs - Execution time in milliseconds
+   */
+  emitToolCallFinish(
+    sessionName: string,
+    toolName: string,
+    args: Record<string, unknown>,
+    result: unknown,
+    durationMs: number,
+  ): void {
+    const event: ToolCallFinishEvent = {
+      type: 'tool_call_finish',
+      sessionName,
+      timestamp: new Date().toISOString(),
+      toolName,
+      argsPreview: JSON.stringify(args).substring(0, MAX_PREVIEW_LENGTH),
+      resultPreview: result ? JSON.stringify(result).substring(0, MAX_PREVIEW_LENGTH) : 'void',
+      durationMs,
+    };
+    this.emit('stream', event);
+  }
+
+  /**
+   * Emit a step finish event.
+   *
+   * @param sessionName - Agent session name
+   * @param stepIndex - Step number (1-based)
+   * @param hasToolCalls - Whether the step included tool calls
+   */
+  emitStepFinish(sessionName: string, stepIndex: number, hasToolCalls: boolean): void {
+    const event: StepFinishEvent = {
+      type: 'step_finish',
+      sessionName,
+      timestamp: new Date().toISOString(),
+      stepIndex,
+      hasToolCalls,
+    };
+    this.emit('stream', event);
+  }
+}

package/packages/crewly-agent/src/runtime/agent-worker.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Tests for Agent Worker IPC protocol and CrewlyAgentRuntimeService worker mode.
+ *
+ * Tests the IPC message types and worker lifecycle without actually forking
+ * a real child process (which would require full AI SDK setup).
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { ParentMessage, WorkerMessage } from './agent-worker.js';
+
+describe('Agent Worker IPC Protocol', () => {
+  describe('ParentMessage types', () => {
+    it('should accept init message with config', () => {
+      const msg: ParentMessage = {
+        type: 'init',
+        config: {
+          model: { provider: 'google', modelId: 'gemini-3-flash-preview' },
+          maxSteps: 500,
+          sessionName: 'test-session',
+          apiBaseUrl: 'http://localhost:8787',
+          systemPrompt: 'You are a test agent.',
+          maxHistoryMessages: 100,
+          compactionThreshold: 0.8,
+        },
+      };
+      expect(msg.type).toBe('init');
+      expect(msg.config.sessionName).toBe('test-session');
+      expect(msg.config.maxSteps).toBe(500);
+    });
+
+    it('should accept run message with optional fields', () => {
+      const msg: ParentMessage = {
+        type: 'run',
+        message: 'Hello',
+        conversationId: 'conv-123',
+        metadata: { channelId: 'C123' },
+      };
+      expect(msg.type).toBe('run');
+      expect(msg.message).toBe('Hello');
+      expect(msg.conversationId).toBe('conv-123');
+    });
+
+    it('should accept run message without optional fields', () => {
+      const msg: ParentMessage = {
+        type: 'run',
+        message: 'Hello',
+      };
+      expect(msg.type).toBe('run');
+      expect(msg.conversationId).toBeUndefined();
+    });
+
+    it('should accept abort message', () => {
+      const msg: ParentMessage = { type: 'abort' };
+      expect(msg.type).toBe('abort');
+    });
+
+    it('should accept get-state message', () => {
+      const msg: ParentMessage = { type: 'get-state' };
+      expect(msg.type).toBe('get-state');
+    });
+
+    it('should accept shutdown message', () => {
+      const msg: ParentMessage = { type: 'shutdown' };
+      expect(msg.type).toBe('shutdown');
+    });
+  });
+
+  describe('WorkerMessage types', () => {
+    it('should accept ready message', () => {
+      const msg: WorkerMessage = { type: 'ready' };
+      expect(msg.type).toBe('ready');
+    });
+
+    it('should accept result message with AgentRunResult', () => {
+      const msg: WorkerMessage = {
+        type: 'result',
+        data: {
+          text: 'Done',
+          steps: 3,
+          usage: { input: 100, output: 50 },
+          toolCalls: [{ toolName: 'bash_exec', args: { command: 'ls' }, result: 'files' }],
+          finishReason: 'stop',
+        },
+      };
+      expect(msg.type).toBe('result');
+      expect(msg.data.steps).toBe(3);
+      expect(msg.data.toolCalls).toHaveLength(1);
+    });
+
+    it('should accept error message with code', () => {
+      const msg: WorkerMessage = {
+        type: 'error',
+        error: 'Init failed: bad API key',
+        code: 'INIT_FAILED',
+      };
+      expect(msg.type).toBe('error');
+      expect(msg.error).toContain('Init failed');
+      expect(msg.code).toBe('INIT_FAILED');
+    });
+
+    it('should accept log message at all levels', () => {
+      const levels: Array<'debug' | 'info' | 'warn' | 'error'> = ['debug', 'info', 'warn', 'error'];
+      for (const level of levels) {
+        const msg: WorkerMessage = { type: 'log', level, message: `Test ${level}` };
+        expect(msg.level).toBe(level);
+      }
+    });
+
+    it('should accept stream text event', () => {
+      const msg: WorkerMessage = {
+        type: 'stream',
+        event: 'text',
+        data: { chunk: 'Hello world' },
+      };
+      expect(msg.type).toBe('stream');
+      expect(msg.event).toBe('text');
+    });
+
+    it('should accept stream toolStart event', () => {
+      const msg: WorkerMessage = {
+        type: 'stream',
+        event: 'toolStart',
+        data: { toolName: 'bash_exec', args: { command: 'npm test' } },
+      };
+      expect(msg.event).toBe('toolStart');
+      expect(msg.data.toolName).toBe('bash_exec');
+    });
+
+    it('should accept stream toolFinish event', () => {
+      const msg: WorkerMessage = {
+        type: 'stream',
+        event: 'toolFinish',
+        data: {
+          toolName: 'bash_exec',
+          args: { command: 'npm test' },
+          result: 'All tests passed',
+          durationMs: 1234,
+        },
+      };
+      expect(msg.event).toBe('toolFinish');
+      expect(msg.data.durationMs).toBe(1234);
+    });
+
+    it('should accept stream stepFinish event', () => {
+      const msg: WorkerMessage = {
+        type: 'stream',
+        event: 'stepFinish',
+        data: { stepIndex: 2, hasToolCalls: true },
+      };
+      expect(msg.event).toBe('stepFinish');
+      expect(msg.data.stepIndex).toBe(2);
+    });
+
+    it('should accept state message', () => {
+      const msg: WorkerMessage = {
+        type: 'state',
+        data: {
+          historyLength: 10,
+          isProcessing: false,
+          isInitialized: true,
+        },
+      };
+      expect(msg.type).toBe('state');
+      expect(msg.data.historyLength).toBe(10);
+    });
+  });
+});
+
+// Worker mode tests for CrewlyAgentRuntimeService are in
+// crewly-agent-runtime.service.test.ts alongside the existing tests,
+// since they share the same mock setup.