groundswell 0.0.1 → 0.0.3

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

@@ -1,210 +0,0 @@
-/**
- * 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

@@ -1,85 +0,0 @@
-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

@@ -1,81 +0,0 @@
-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

@@ -1,244 +0,0 @@
-/**
- * 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');
-}