groundswell 0.0.1

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

@@ -0,0 +1,210 @@
+/**
+ * Unit tests for ReflectionManager
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ReflectionManager } from '../../reflection/reflection.js';
+import type { ReflectionContext, WorkflowNode } from '../../types/index.js';
+
+describe('ReflectionManager', () => {
+  const createTestNode = (): WorkflowNode => ({
+    id: 'test-node-1',
+    name: 'Test Node',
+    parent: null,
+    children: [],
+    status: 'failed',
+    logs: [],
+    events: [],
+    stateSnapshot: null,
+  });
+
+  const createContext = (
+    error: Error,
+    attemptNumber: number = 1
+  ): ReflectionContext => ({
+    level: 'workflow',
+    failedNode: createTestNode(),
+    error,
+    attemptNumber,
+    previousAttempts: [],
+  });
+
+  describe('isEnabled', () => {
+    it('should return true when enabled', () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      expect(manager.isEnabled()).toBe(true);
+    });
+
+    it('should return false when disabled', () => {
+      const manager = new ReflectionManager({ enabled: false, maxAttempts: 3 });
+      expect(manager.isEnabled()).toBe(false);
+    });
+  });
+
+  describe('getMaxAttempts', () => {
+    it('should return configured maxAttempts', () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 5 });
+      expect(manager.getMaxAttempts()).toBe(5);
+    });
+  });
+
+  describe('getRetryDelayMs', () => {
+    it('should return 0 when not configured', () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      expect(manager.getRetryDelayMs()).toBe(0);
+    });
+
+    it('should return configured delay', () => {
+      const manager = new ReflectionManager({
+        enabled: true,
+        maxAttempts: 3,
+        retryDelayMs: 1000,
+      });
+      expect(manager.getRetryDelayMs()).toBe(1000);
+    });
+  });
+
+  describe('triggerReflection', () => {
+    it('should throw when reflection is disabled', async () => {
+      const manager = new ReflectionManager({ enabled: false, maxAttempts: 3 });
+
+      await expect(manager.triggerReflection()).rejects.toThrow(
+        'Reflection is not enabled'
+      );
+    });
+
+    it('should record reflection in history', async () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+
+      await manager.triggerReflection('test reason');
+
+      const history = manager.getReflectionHistory();
+      expect(history).toHaveLength(1);
+      expect(history[0].reason).toBe('test reason');
+    });
+  });
+
+  describe('getReflectionHistory', () => {
+    it('should return empty array initially', () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      expect(manager.getReflectionHistory()).toEqual([]);
+    });
+
+    it('should return copy of history (not reference)', () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      const history1 = manager.getReflectionHistory();
+      const history2 = manager.getReflectionHistory();
+
+      expect(history1).not.toBe(history2);
+    });
+  });
+
+  describe('reflect (heuristic mode)', () => {
+    it('should not retry rate limit errors', async () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      const context = createContext(new Error('rate limit exceeded'));
+
+      const result = await manager.reflect(context);
+
+      expect(result.shouldRetry).toBe(false);
+      expect(result.reason).toContain('Non-retryable error');
+    });
+
+    it('should not retry authentication errors', async () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      const context = createContext(new Error('authentication failed'));
+
+      const result = await manager.reflect(context);
+
+      expect(result.shouldRetry).toBe(false);
+    });
+
+    it('should retry validation errors', async () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      const context = createContext(new Error('validation failed: missing field'));
+
+      const result = await manager.reflect(context);
+
+      expect(result.shouldRetry).toBe(true);
+      expect(result.reason).toContain('Validation/parsing error');
+    });
+
+    it('should retry JSON parse errors', async () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      const context = createContext(new Error('JSON parse error at position 10'));
+
+      const result = await manager.reflect(context);
+
+      expect(result.shouldRetry).toBe(true);
+    });
+
+    it('should retry timeout errors (up to limit)', async () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+
+      const context1 = createContext(new Error('timeout'), 1);
+      const result1 = await manager.reflect(context1);
+      expect(result1.shouldRetry).toBe(true);
+
+      const context2 = createContext(new Error('timeout'), 2);
+      const result2 = await manager.reflect(context2);
+      expect(result2.shouldRetry).toBe(false);
+    });
+
+    it('should stop retrying after max attempts', async () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 2 });
+      const context = createContext(new Error('generic error'), 2);
+
+      const result = await manager.reflect(context);
+
+      expect(result.shouldRetry).toBe(false);
+      expect(result.reason).toContain('Max attempts');
+    });
+
+    it('should record reflection in history', async () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      const context = createContext(new Error('test error'));
+
+      await manager.reflect(context);
+
+      const history = manager.getReflectionHistory();
+      expect(history).toHaveLength(1);
+      expect(history[0].level).toBe('workflow');
+      expect(history[0].error.message).toBe('test error');
+    });
+  });
+
+  describe('markLastReflectionSuccessful', () => {
+    it('should mark last entry as successful', async () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      const context = createContext(new Error('test error'));
+
+      await manager.reflect(context);
+      manager.markLastReflectionSuccessful();
+
+      const history = manager.getReflectionHistory();
+      expect(history[0].success).toBe(true);
+    });
+
+    it('should do nothing when history is empty', () => {
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+
+      // Should not throw
+      expect(() => manager.markLastReflectionSuccessful()).not.toThrow();
+    });
+  });
+
+  describe('event emission', () => {
+    it('should emit reflectionStart and reflectionEnd events', async () => {
+      const events: { type: string }[] = [];
+      const manager = new ReflectionManager({ enabled: true, maxAttempts: 3 });
+      manager.setEventEmitter((event) => events.push(event));
+
+      const context = createContext(new Error('test error'));
+      await manager.reflect(context);
+
+      expect(events).toHaveLength(2);
+      expect(events[0].type).toBe('reflectionStart');
+      expect(events[1].type).toBe('reflectionEnd');
+    });
+  });
+});

package/src/__tests__/unit/tree-debugger.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import { Workflow, WorkflowTreeDebugger } from '../../index.js';
+
+class DebugTestWorkflow extends Workflow {
+  async run(): Promise<void> {
+    this.setStatus('completed');
+  }
+}
+
+describe('WorkflowTreeDebugger', () => {
+  it('should render tree string', () => {
+    const wf = new DebugTestWorkflow('Root');
+    const debugger_ = new WorkflowTreeDebugger(wf);
+
+    const tree = debugger_.toTreeString();
+    expect(tree).toContain('Root');
+    expect(tree).toContain('[idle]');
+  });
+
+  it('should show child nodes in tree', () => {
+    const parent = new DebugTestWorkflow('Parent');
+    const child1 = new DebugTestWorkflow('Child1', parent);
+    const child2 = new DebugTestWorkflow('Child2', parent);
+
+    const debugger_ = new WorkflowTreeDebugger(parent);
+    const tree = debugger_.toTreeString();
+
+    expect(tree).toContain('Parent');
+    expect(tree).toContain('Child1');
+    expect(tree).toContain('Child2');
+    expect(tree).toContain('├──');
+    expect(tree).toContain('└──');
+  });
+
+  it('should find node by ID', () => {
+    const parent = new DebugTestWorkflow('Parent');
+    const child = new DebugTestWorkflow('Child', parent);
+
+    const debugger_ = new WorkflowTreeDebugger(parent);
+
+    expect(debugger_.getNode(parent.id)).toBe(parent.getNode());
+    expect(debugger_.getNode(child.id)).toBe(child.getNode());
+    expect(debugger_.getNode('nonexistent')).toBeUndefined();
+  });
+
+  it('should collect logs from all nodes', async () => {
+    const parent = new DebugTestWorkflow('Parent');
+    const child = new DebugTestWorkflow('Child', parent);
+
+    const debugger_ = new WorkflowTreeDebugger(parent);
+
+    // Add some logs manually
+    parent.getNode().logs.push({
+      id: '1',
+      workflowId: parent.id,
+      timestamp: Date.now(),
+      level: 'info',
+      message: 'Parent log',
+    });
+
+    child.getNode().logs.push({
+      id: '2',
+      workflowId: child.id,
+      timestamp: Date.now(),
+      level: 'info',
+      message: 'Child log',
+    });
+
+    const logString = debugger_.toLogString();
+    expect(logString).toContain('Parent log');
+    expect(logString).toContain('Child log');
+  });
+
+  it('should return stats', () => {
+    const parent = new DebugTestWorkflow('Parent');
+    new DebugTestWorkflow('Child1', parent);
+    new DebugTestWorkflow('Child2', parent);
+
+    const debugger_ = new WorkflowTreeDebugger(parent);
+    const stats = debugger_.getStats();
+
+    expect(stats.totalNodes).toBe(3);
+    expect(stats.byStatus.idle).toBe(3);
+  });
+});

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

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { Workflow, WorkflowObserver, WorkflowNode, LogEntry, WorkflowEvent } from '../../index.js';
+
+class SimpleWorkflow extends Workflow {
+  async run(): Promise<string> {
+    this.setStatus('running');
+    this.logger.info('Running simple workflow');
+    this.setStatus('completed');
+    return 'done';
+  }
+}
+
+describe('Workflow', () => {
+  it('should create with unique id', () => {
+    const wf1 = new SimpleWorkflow();
+    const wf2 = new SimpleWorkflow();
+    expect(wf1.id).not.toBe(wf2.id);
+  });
+
+  it('should use class name as default name', () => {
+    const wf = new SimpleWorkflow();
+    expect(wf.getNode().name).toBe('SimpleWorkflow');
+  });
+
+  it('should use custom name when provided', () => {
+    const wf = new SimpleWorkflow('CustomName');
+    expect(wf.getNode().name).toBe('CustomName');
+  });
+
+  it('should start with idle status', () => {
+    const wf = new SimpleWorkflow();
+    expect(wf.status).toBe('idle');
+    expect(wf.getNode().status).toBe('idle');
+  });
+
+  it('should attach child to parent', () => {
+    const parent = new SimpleWorkflow('Parent');
+    const child = new SimpleWorkflow('Child', parent);
+
+    expect(child.parent).toBe(parent);
+    expect(parent.children).toContain(child);
+    expect(parent.getNode().children).toContain(child.getNode());
+  });
+
+  it('should emit logs to observers', async () => {
+    const wf = new SimpleWorkflow();
+    const logs: LogEntry[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: (entry) => logs.push(entry),
+      onEvent: () => {},
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    wf.addObserver(observer);
+    await wf.run();
+
+    expect(logs.length).toBeGreaterThan(0);
+    expect(logs[0].message).toBe('Running simple workflow');
+  });
+
+  it('should emit childAttached event', () => {
+    const parent = new SimpleWorkflow('Parent');
+    const events: WorkflowEvent[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: (event) => events.push(event),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    parent.addObserver(observer);
+    const child = new SimpleWorkflow('Child', parent);
+
+    const attachEvent = events.find((e) => e.type === 'childAttached');
+    expect(attachEvent).toBeDefined();
+    expect(attachEvent?.type === 'childAttached' && attachEvent.parentId).toBe(parent.id);
+  });
+});

package/src/cache/cache-key.ts

@@ -0,0 +1,244 @@
+/**
+ * Cache Key Generation - Deterministic key generation for LLM response caching
+ *
+ * Uses SHA-256 hashing with deterministic JSON serialization to ensure
+ * identical inputs always produce identical cache keys.
+ */
+
+import { createHash } from 'node:crypto';
+import type { Tool, MCPServer, Skill } from '../types/index.js';
+import type { z } from 'zod';
+
+/**
+ * Inputs used to generate a cache key
+ */
+export interface CacheKeyInputs {
+  /** User message content */
+  user: string;
+  /** Data passed to the prompt */
+  data?: Record<string, unknown>;
+  /** System prompt */
+  system?: string;
+  /** Model identifier */
+  model: string;
+  /** Temperature setting */
+  temperature?: number;
+  /** Maximum tokens */
+  maxTokens?: number;
+  /** Tools available to the agent */
+  tools?: Tool[];
+  /** MCP servers */
+  mcps?: MCPServer[];
+  /** Skills */
+  skills?: Skill[];
+  /** Zod response format schema */
+  responseFormat?: z.ZodType;
+}
+
+/**
+ * Deterministically stringify a value with sorted object keys
+ *
+ * Unlike JSON.stringify, this function guarantees consistent output
+ * regardless of key insertion order by sorting all object keys.
+ *
+ * @param value - Value to stringify
+ * @returns Deterministic JSON string
+ * @throws TypeError if circular reference detected
+ */
+export function deterministicStringify(value: unknown): string {
+  const seen = new WeakSet<object>();
+
+  function stringify(val: unknown): string {
+    if (val === null) return 'null';
+    if (val === undefined) return 'undefined';
+    if (typeof val === 'string') return JSON.stringify(val);
+    if (typeof val === 'number') {
+      if (Number.isNaN(val)) return 'NaN';
+      if (!Number.isFinite(val)) return val > 0 ? 'Infinity' : '-Infinity';
+      return String(val);
+    }
+    if (typeof val === 'boolean') return String(val);
+    if (typeof val === 'function') return 'function';
+    if (typeof val === 'symbol') return 'symbol';
+    if (typeof val === 'bigint') return `${val}n`;
+
+    if (typeof val === 'object') {
+      if (seen.has(val as object)) {
+        throw new TypeError('Converting circular structure to JSON');
+      }
+      seen.add(val as object);
+
+      let result: string;
+
+      if (Array.isArray(val)) {
+        result = '[' + val.map(stringify).join(',') + ']';
+      } else if (val instanceof Date) {
+        result = JSON.stringify(val.toISOString());
+      } else if (val instanceof Map) {
+        const entries = Array.from(val.entries())
+          .sort(([a], [b]) => String(a).localeCompare(String(b)))
+          .map(([k, v]) => `[${stringify(k)},${stringify(v)}]`);
+        result = `Map{${entries.join(',')}}`;
+      } else if (val instanceof Set) {
+        const values = Array.from(val)
+          .map(stringify)
+          .sort();
+        result = `Set{${values.join(',')}}`;
+      } else {
+        // Regular object - sort keys
+        const keys = Object.keys(val as Record<string, unknown>).sort();
+        const pairs = keys.map(
+          (k) =>
+            JSON.stringify(k) +
+            ':' +
+            stringify((val as Record<string, unknown>)[k])
+        );
+        result = '{' + pairs.join(',') + '}';
+      }
+
+      seen.delete(val as object);
+      return result;
+    }
+
+    return String(val);
+  }
+
+  return stringify(value);
+}
+
+/**
+ * Generate a hash from a Zod schema's internal definition
+ *
+ * Zod schemas are functions that cannot be directly serialized.
+ * This extracts the schema's _def property which contains the
+ * schema structure and hashes it.
+ *
+ * @param schema - Zod schema to hash
+ * @returns SHA-256 hex digest of the schema definition
+ */
+export function getSchemaHash(schema: z.ZodType | undefined): string {
+  if (!schema) {
+    return 'no-schema';
+  }
+
+  try {
+    // Access Zod's internal _def property
+    const def = (schema as { _def?: unknown })._def;
+    if (!def) {
+      return 'unknown-schema';
+    }
+
+    // Create a simplified representation of the schema
+    const schemaRep = extractSchemaStructure(def);
+    const serialized = deterministicStringify(schemaRep);
+
+    return createHash('sha256').update(serialized, 'utf8').digest('hex');
+  } catch {
+    // Fallback for schemas that can't be introspected
+    return 'fallback-schema';
+  }
+}
+
+/**
+ * Extract a serializable structure from a Zod schema definition
+ */
+function extractSchemaStructure(def: unknown): unknown {
+  if (def === null || def === undefined) {
+    return def;
+  }
+
+  if (typeof def !== 'object') {
+    return def;
+  }
+
+  const typedDef = def as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+
+  // Extract key properties that define schema structure
+  if ('typeName' in typedDef) {
+    result.typeName = typedDef.typeName;
+  }
+
+  if ('shape' in typedDef && typeof typedDef.shape === 'function') {
+    // Object schema - extract shape
+    try {
+      const shape = typedDef.shape() as Record<string, { _def?: unknown }>;
+      result.shape = Object.fromEntries(
+        Object.entries(shape).map(([key, value]) => [
+          key,
+          extractSchemaStructure(value?._def),
+        ])
+      );
+    } catch {
+      result.shape = 'complex-shape';
+    }
+  }
+
+  if ('type' in typedDef && typedDef.type && typeof typedDef.type === 'object') {
+    result.type = extractSchemaStructure((typedDef.type as { _def?: unknown })._def);
+  }
+
+  if ('values' in typedDef) {
+    result.values = typedDef.values;
+  }
+
+  if ('checks' in typedDef && Array.isArray(typedDef.checks)) {
+    result.checks = typedDef.checks.map((check: { kind?: string }) => check.kind);
+  }
+
+  return result;
+}
+
+/**
+ * Generate a deterministic cache key from prompt execution inputs
+ *
+ * The key is a 64-character SHA-256 hex digest that uniquely identifies
+ * a specific combination of prompt, data, configuration, and tools.
+ *
+ * @param inputs - Cache key inputs
+ * @returns 64-character hex SHA-256 digest
+ */
+export function generateCacheKey(inputs: CacheKeyInputs): string {
+  // Build normalized representation with sorted arrays
+  const normalized: Record<string, unknown> = {
+    user: inputs.user,
+    model: inputs.model,
+  };
+
+  // Include optional fields only if defined
+  if (inputs.data !== undefined) {
+    normalized.data = inputs.data;
+  }
+
+  if (inputs.system !== undefined) {
+    normalized.system = inputs.system;
+  }
+
+  if (inputs.temperature !== undefined) {
+    normalized.temperature = inputs.temperature;
+  }
+
+  if (inputs.maxTokens !== undefined) {
+    normalized.maxTokens = inputs.maxTokens;
+  }
+
+  // Sort tool/mcp/skill names for determinism
+  if (inputs.tools && inputs.tools.length > 0) {
+    normalized.tools = inputs.tools.map((t) => t.name).sort();
+  }
+
+  if (inputs.mcps && inputs.mcps.length > 0) {
+    normalized.mcps = inputs.mcps.map((m) => m.name).sort();
+  }
+
+  if (inputs.skills && inputs.skills.length > 0) {
+    normalized.skills = inputs.skills.map((s) => s.name).sort();
+  }
+
+  // Include schema hash
+  normalized.schemaHash = getSchemaHash(inputs.responseFormat);
+
+  // Generate SHA-256 hash
+  const serialized = deterministicStringify(normalized);
+  return createHash('sha256').update(serialized, 'utf8').digest('hex');
+}