groundswell 0.0.1

package/src/__tests__/unit/agent.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Agent } from '../../core/agent.js';
+import { MCPHandler } from '../../core/mcp-handler.js';
+
+describe('Agent', () => {
+  it('should create with unique id', () => {
+    const a1 = new Agent();
+    const a2 = new Agent();
+    expect(a1.id).not.toBe(a2.id);
+  });
+
+  it('should use default name when not provided', () => {
+    const agent = new Agent();
+    expect(agent.name).toBe('Agent');
+  });
+
+  it('should use custom name when provided', () => {
+    const agent = new Agent({ name: 'CustomAgent' });
+    expect(agent.name).toBe('CustomAgent');
+  });
+
+  it('should provide access to MCP handler', () => {
+    const agent = new Agent();
+    const handler = agent.getMcpHandler();
+    expect(handler).toBeInstanceOf(MCPHandler);
+  });
+
+  it('should register MCP servers from config', () => {
+    const agent = new Agent({
+      mcps: [
+        {
+          name: 'test-mcp',
+          transport: 'inprocess',
+          tools: [
+            {
+              name: 'test_tool',
+              description: 'A test tool',
+              input_schema: { type: 'object', properties: {} },
+            },
+          ],
+        },
+      ],
+    });
+
+    const handler = agent.getMcpHandler();
+    expect(handler.getServerNames()).toContain('test-mcp');
+    expect(handler.hasTool('test-mcp__test_tool')).toBe(true);
+  });
+});
+
+describe('MCPHandler', () => {
+  it('should register and unregister servers', () => {
+    const handler = new MCPHandler();
+
+    handler.registerServer({
+      name: 'server1',
+      transport: 'inprocess',
+    });
+
+    expect(handler.getServerNames()).toContain('server1');
+
+    handler.unregisterServer('server1');
+    expect(handler.getServerNames()).not.toContain('server1');
+  });
+
+  it('should throw when registering duplicate server', () => {
+    const handler = new MCPHandler();
+
+    handler.registerServer({
+      name: 'server1',
+      transport: 'inprocess',
+    });
+
+    expect(() =>
+      handler.registerServer({
+        name: 'server1',
+        transport: 'inprocess',
+      })
+    ).toThrow("MCP server 'server1' is already registered");
+  });
+
+  it('should convert tools to full names', () => {
+    const handler = new MCPHandler();
+
+    handler.registerServer({
+      name: 'myserver',
+      transport: 'inprocess',
+      tools: [
+        {
+          name: 'tool1',
+          description: 'Tool 1',
+          input_schema: { type: 'object', properties: {} },
+        },
+        {
+          name: 'tool2',
+          description: 'Tool 2',
+          input_schema: { type: 'object', properties: {} },
+        },
+      ],
+    });
+
+    const tools = handler.getTools();
+    expect(tools).toHaveLength(2);
+    expect(tools[0].name).toBe('myserver__tool1');
+    expect(tools[1].name).toBe('myserver__tool2');
+  });
+
+  it('should execute registered tool', async () => {
+    const handler = new MCPHandler();
+
+    handler.registerServer({
+      name: 'math',
+      transport: 'inprocess',
+      tools: [
+        {
+          name: 'add',
+          description: 'Add two numbers',
+          input_schema: {
+            type: 'object',
+            properties: {
+              a: { type: 'number' },
+              b: { type: 'number' },
+            },
+          },
+        },
+      ],
+    });
+
+    handler.registerToolExecutor('math', 'add', async (input: unknown) => {
+      const { a, b } = input as { a: number; b: number };
+      return a + b;
+    });
+
+    const result = await handler.executeTool('math__add', { a: 2, b: 3 });
+    expect(result.content).toBe('5');
+    expect(result.is_error).toBeUndefined();
+  });
+
+  it('should return error for unknown tool', async () => {
+    const handler = new MCPHandler();
+    const result = await handler.executeTool('unknown__tool', {});
+    expect(result.is_error).toBe(true);
+    expect(result.content).toContain('not found');
+  });
+
+  it('should return error when tool throws', async () => {
+    const handler = new MCPHandler();
+
+    handler.registerServer({
+      name: 'failing',
+      transport: 'inprocess',
+      tools: [
+        {
+          name: 'fail',
+          description: 'Always fails',
+          input_schema: { type: 'object', properties: {} },
+        },
+      ],
+    });
+
+    handler.registerToolExecutor('failing', 'fail', async () => {
+      throw new Error('Tool error');
+    });
+
+    const result = await handler.executeTool('failing__fail', {});
+    expect(result.is_error).toBe(true);
+    expect(result.content).toContain('Tool error');
+  });
+});

package/src/__tests__/unit/cache-key.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Unit tests for cache key generation
+ */
+
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import {
+  deterministicStringify,
+  generateCacheKey,
+  getSchemaHash,
+} from '../../cache/cache-key.js';
+
+describe('deterministicStringify', () => {
+  it('should produce same output for same object regardless of key order', () => {
+    const obj1 = { b: 2, a: 1 };
+    const obj2 = { a: 1, b: 2 };
+
+    expect(deterministicStringify(obj1)).toBe(deterministicStringify(obj2));
+  });
+
+  it('should handle primitives correctly', () => {
+    expect(deterministicStringify(null)).toBe('null');
+    expect(deterministicStringify(undefined)).toBe('undefined');
+    expect(deterministicStringify(true)).toBe('true');
+    expect(deterministicStringify(false)).toBe('false');
+    expect(deterministicStringify(42)).toBe('42');
+    expect(deterministicStringify('hello')).toBe('"hello"');
+  });
+
+  it('should handle arrays correctly', () => {
+    expect(deterministicStringify([1, 2, 3])).toBe('[1,2,3]');
+    expect(deterministicStringify(['a', 'b'])).toBe('["a","b"]');
+  });
+
+  it('should handle nested objects with sorted keys', () => {
+    const obj = { z: { b: 2, a: 1 }, y: [3, 2, 1] };
+    const result = deterministicStringify(obj);
+
+    // Keys should be sorted: y before z, a before b
+    expect(result).toBe('{"y":[3,2,1],"z":{"a":1,"b":2}}');
+  });
+
+  it('should throw on circular references', () => {
+    const obj: Record<string, unknown> = { a: 1 };
+    obj.self = obj;
+
+    expect(() => deterministicStringify(obj)).toThrow(
+      'Converting circular structure to JSON'
+    );
+  });
+
+  it('should handle Date objects', () => {
+    const date = new Date('2024-01-15T10:30:00.000Z');
+    const result = deterministicStringify(date);
+
+    expect(result).toBe('"2024-01-15T10:30:00.000Z"');
+  });
+
+  it('should handle Map objects', () => {
+    const map = new Map([
+      ['z', 1],
+      ['a', 2],
+    ]);
+    const result = deterministicStringify(map);
+
+    // Keys should be sorted in the output
+    expect(result).toContain('Map{');
+    expect(result).toContain('"a"');
+    expect(result).toContain('"z"');
+  });
+
+  it('should handle Set objects', () => {
+    const set = new Set([3, 1, 2]);
+    const result = deterministicStringify(set);
+
+    expect(result).toContain('Set{');
+  });
+});
+
+describe('getSchemaHash', () => {
+  it('should produce consistent hash for same schema', () => {
+    const schema1 = z.object({ name: z.string() });
+    const schema2 = z.object({ name: z.string() });
+
+    expect(getSchemaHash(schema1)).toBe(getSchemaHash(schema2));
+  });
+
+  it('should produce different hashes for different schemas', () => {
+    const schema1 = z.object({ name: z.string() });
+    const schema2 = z.object({ age: z.number() });
+
+    expect(getSchemaHash(schema1)).not.toBe(getSchemaHash(schema2));
+  });
+
+  it('should handle undefined schema', () => {
+    expect(getSchemaHash(undefined)).toBe('no-schema');
+  });
+
+  it('should produce 64-character hex string', () => {
+    const schema = z.object({ value: z.number() });
+    const hash = getSchemaHash(schema);
+
+    expect(hash).toMatch(/^[a-f0-9]{64}$/);
+  });
+});
+
+describe('generateCacheKey', () => {
+  it('should produce same key for identical inputs', () => {
+    const inputs1 = {
+      user: 'Hello',
+      model: 'claude-sonnet-4-20250514',
+      data: { value: 42 },
+    };
+    const inputs2 = {
+      user: 'Hello',
+      model: 'claude-sonnet-4-20250514',
+      data: { value: 42 },
+    };
+
+    expect(generateCacheKey(inputs1)).toBe(generateCacheKey(inputs2));
+  });
+
+  it('should produce different keys for different inputs', () => {
+    const inputs1 = {
+      user: 'Hello',
+      model: 'claude-sonnet-4-20250514',
+    };
+    const inputs2 = {
+      user: 'Goodbye',
+      model: 'claude-sonnet-4-20250514',
+    };
+
+    expect(generateCacheKey(inputs1)).not.toBe(generateCacheKey(inputs2));
+  });
+
+  it('should produce 64-character hex string', () => {
+    const key = generateCacheKey({
+      user: 'Test',
+      model: 'claude-sonnet-4-20250514',
+    });
+
+    expect(key).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  it('should include tools in key generation (sorted)', () => {
+    const toolSchema = { type: 'object' as const, properties: {}, required: [] };
+    const inputs1 = {
+      user: 'Hello',
+      model: 'claude-sonnet-4-20250514',
+      tools: [
+        { name: 'tool_b', description: 'B', input_schema: toolSchema },
+        { name: 'tool_a', description: 'A', input_schema: toolSchema },
+      ],
+    };
+    const inputs2 = {
+      user: 'Hello',
+      model: 'claude-sonnet-4-20250514',
+      tools: [
+        { name: 'tool_a', description: 'A', input_schema: toolSchema },
+        { name: 'tool_b', description: 'B', input_schema: toolSchema },
+      ],
+    };
+
+    // Same tools in different order should produce same key
+    expect(generateCacheKey(inputs1)).toBe(generateCacheKey(inputs2));
+  });
+
+  it('should include schema hash in key', () => {
+    const schema = z.object({ result: z.string() });
+    const inputs1 = {
+      user: 'Hello',
+      model: 'claude-sonnet-4-20250514',
+      responseFormat: schema,
+    };
+    const inputs2 = {
+      user: 'Hello',
+      model: 'claude-sonnet-4-20250514',
+    };
+
+    expect(generateCacheKey(inputs1)).not.toBe(generateCacheKey(inputs2));
+  });
+});

package/src/__tests__/unit/cache.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Unit tests for LLMCache
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { LLMCache } from '../../cache/cache.js';
+
+describe('LLMCache', () => {
+  let cache: LLMCache;
+
+  beforeEach(() => {
+    cache = new LLMCache({ maxItems: 10 });
+  });
+
+  describe('get/set', () => {
+    it('should store and retrieve values', async () => {
+      await cache.set('key1', { data: 'test' });
+      const result = await cache.get('key1');
+
+      expect(result).toEqual({ data: 'test' });
+    });
+
+    it('should return undefined for missing keys', async () => {
+      const result = await cache.get('nonexistent');
+
+      expect(result).toBeUndefined();
+    });
+
+    it('should update existing keys', async () => {
+      await cache.set('key1', 'first');
+      await cache.set('key1', 'second');
+
+      const result = await cache.get('key1');
+      expect(result).toBe('second');
+    });
+  });
+
+  describe('has', () => {
+    it('should return true for existing keys', async () => {
+      await cache.set('key1', 'value');
+
+      expect(cache.has('key1')).toBe(true);
+    });
+
+    it('should return false for missing keys', () => {
+      expect(cache.has('nonexistent')).toBe(false);
+    });
+  });
+
+  describe('bust', () => {
+    it('should remove specific key', async () => {
+      await cache.set('key1', 'value1');
+      await cache.set('key2', 'value2');
+
+      await cache.bust('key1');
+
+      expect(cache.has('key1')).toBe(false);
+      expect(cache.has('key2')).toBe(true);
+    });
+
+    it('should not throw for missing keys', async () => {
+      await expect(cache.bust('nonexistent')).resolves.not.toThrow();
+    });
+  });
+
+  describe('bustPrefix', () => {
+    it('should remove all keys with given prefix', async () => {
+      await cache.set('key1', 'value1', { prefix: 'group-a' });
+      await cache.set('key2', 'value2', { prefix: 'group-a' });
+      await cache.set('key3', 'value3', { prefix: 'group-b' });
+
+      await cache.bustPrefix('group-a');
+
+      expect(cache.has('key1')).toBe(false);
+      expect(cache.has('key2')).toBe(false);
+      expect(cache.has('key3')).toBe(true);
+    });
+
+    it('should not throw for nonexistent prefix', async () => {
+      await expect(cache.bustPrefix('nonexistent')).resolves.not.toThrow();
+    });
+  });
+
+  describe('clear', () => {
+    it('should remove all entries', async () => {
+      await cache.set('key1', 'value1');
+      await cache.set('key2', 'value2');
+
+      await cache.clear();
+
+      expect(cache.size).toBe(0);
+    });
+
+    it('should reset metrics', async () => {
+      await cache.set('key1', 'value1');
+      await cache.get('key1'); // hit
+      await cache.get('key2'); // miss
+
+      await cache.clear();
+
+      const metrics = cache.metrics();
+      expect(metrics.hits).toBe(0);
+      expect(metrics.misses).toBe(0);
+    });
+  });
+
+  describe('metrics', () => {
+    it('should track hits and misses', async () => {
+      await cache.set('key1', 'value1');
+
+      await cache.get('key1'); // hit
+      await cache.get('key1'); // hit
+      await cache.get('key2'); // miss
+
+      const metrics = cache.metrics();
+      expect(metrics.hits).toBe(2);
+      expect(metrics.misses).toBe(1);
+      expect(metrics.hitRate).toBeCloseTo(66.67, 0);
+    });
+
+    it('should track size', async () => {
+      await cache.set('key1', 'value1');
+      await cache.set('key2', 'value2');
+
+      const metrics = cache.metrics();
+      expect(metrics.size).toBe(2);
+    });
+  });
+
+  describe('LRU eviction', () => {
+    it('should evict least recently used items when maxItems exceeded', async () => {
+      const smallCache = new LLMCache({ maxItems: 3 });
+
+      await smallCache.set('key1', 'value1');
+      await smallCache.set('key2', 'value2');
+      await smallCache.set('key3', 'value3');
+      await smallCache.set('key4', 'value4');
+
+      // key1 should be evicted (least recently used)
+      expect(smallCache.has('key1')).toBe(false);
+      expect(smallCache.has('key4')).toBe(true);
+    });
+
+    it('should update LRU order on get', async () => {
+      const smallCache = new LLMCache({ maxItems: 3 });
+
+      await smallCache.set('key1', 'value1');
+      await smallCache.set('key2', 'value2');
+      await smallCache.set('key3', 'value3');
+
+      // Access key1 to make it most recently used
+      await smallCache.get('key1');
+
+      // Add new item, should evict key2 instead of key1
+      await smallCache.set('key4', 'value4');
+
+      expect(smallCache.has('key1')).toBe(true);
+      expect(smallCache.has('key2')).toBe(false);
+    });
+  });
+
+  describe('keys', () => {
+    it('should return iterator of all keys', async () => {
+      await cache.set('key1', 'value1');
+      await cache.set('key2', 'value2');
+
+      const keys = Array.from(cache.keys());
+      expect(keys).toContain('key1');
+      expect(keys).toContain('key2');
+    });
+  });
+});

package/src/__tests__/unit/context.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest';
+import {
+  getExecutionContext,
+  requireExecutionContext,
+  runInContext,
+  runInContextSync,
+  hasExecutionContext,
+  createChildContext,
+  type AgentExecutionContext,
+} from '../../core/context.js';
+import type { WorkflowNode, WorkflowEvent } from '../../types/index.js';
+
+describe('AgentExecutionContext', () => {
+  const createMockNode = (name: string): WorkflowNode => ({
+    id: `node-${name}`,
+    name,
+    parent: null,
+    children: [],
+    status: 'running',
+    logs: [],
+    events: [],
+    stateSnapshot: null,
+  });
+
+  const createMockContext = (name: string): AgentExecutionContext => ({
+    workflowNode: createMockNode(name),
+    emitEvent: () => {},
+    workflowId: `workflow-${name}`,
+  });
+
+  it('should return undefined outside of context', () => {
+    expect(getExecutionContext()).toBeUndefined();
+  });
+
+  it('should throw when requiring context outside of context', () => {
+    expect(() => requireExecutionContext('test operation')).toThrow(
+      'test operation called outside of workflow context'
+    );
+  });
+
+  it('should detect context availability', () => {
+    expect(hasExecutionContext()).toBe(false);
+  });
+
+  it('should provide context within runInContext', async () => {
+    const ctx = createMockContext('test');
+
+    await runInContext(ctx, async () => {
+      expect(hasExecutionContext()).toBe(true);
+      expect(getExecutionContext()).toBe(ctx);
+      expect(requireExecutionContext('test')).toBe(ctx);
+    });
+
+    // Context should be gone after run completes
+    expect(hasExecutionContext()).toBe(false);
+  });
+
+  it('should provide context within sync runInContextSync', () => {
+    const ctx = createMockContext('test');
+
+    runInContextSync(ctx, () => {
+      expect(hasExecutionContext()).toBe(true);
+      expect(getExecutionContext()).toBe(ctx);
+    });
+
+    expect(hasExecutionContext()).toBe(false);
+  });
+
+  it('should propagate context through nested async calls', async () => {
+    const ctx = createMockContext('root');
+
+    const nested = async () => {
+      const innerCtx = getExecutionContext();
+      return innerCtx?.workflowNode.name;
+    };
+
+    await runInContext(ctx, async () => {
+      const name = await nested();
+      expect(name).toBe('root');
+    });
+  });
+
+  it('should create child context with new node', async () => {
+    const parentCtx = createMockContext('parent');
+    const childNode = createMockNode('child');
+
+    await runInContext(parentCtx, async () => {
+      const childCtx = createChildContext(childNode);
+      expect(childCtx).toBeDefined();
+      expect(childCtx?.workflowNode).toBe(childNode);
+      expect(childCtx?.workflowId).toBe(parentCtx.workflowId);
+    });
+  });
+
+  it('should return undefined for child context when not in context', () => {
+    const childNode = createMockNode('child');
+    const childCtx = createChildContext(childNode);
+    expect(childCtx).toBeUndefined();
+  });
+
+  it('should allow nested contexts', async () => {
+    const outerCtx = createMockContext('outer');
+    const innerCtx = createMockContext('inner');
+
+    await runInContext(outerCtx, async () => {
+      expect(getExecutionContext()?.workflowNode.name).toBe('outer');
+
+      await runInContext(innerCtx, async () => {
+        expect(getExecutionContext()?.workflowNode.name).toBe('inner');
+      });
+
+      // Should restore outer context
+      expect(getExecutionContext()?.workflowNode.name).toBe('outer');
+    });
+  });
+
+  it('should capture emitted events', async () => {
+    const events: WorkflowEvent[] = [];
+    const node = createMockNode('test');
+    const ctx: AgentExecutionContext = {
+      workflowNode: node,
+      emitEvent: (event) => events.push(event),
+      workflowId: 'wf-1',
+    };
+
+    await runInContext(ctx, async () => {
+      const currentCtx = requireExecutionContext('emit');
+      currentCtx.emitEvent({
+        type: 'stepStart',
+        node: currentCtx.workflowNode,
+        step: 'test-step',
+      });
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe('stepStart');
+  });
+});