groundswell 0.0.1 → 0.0.2

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { Workflow, WorkflowObserver, WorkflowNode, LogEntry, WorkflowEvent } from '../../index.js';
+import { Workflow, WorkflowObserver, WorkflowNode, LogEntry, WorkflowEvent, ObservedState, getObservedState } from '../../index.js';
 
 class SimpleWorkflow extends Workflow {
   async run(): Promise<string> {
@@ -10,6 +10,80 @@ class SimpleWorkflow extends Workflow {
   }
 }
 
+describe('Workflow Name Validation', () => {
+  it('should reject empty string name', () => {
+    expect(() => new SimpleWorkflow('')).toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  it('should reject whitespace-only name (spaces)', () => {
+    expect(() => new SimpleWorkflow('   ')).toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  it('should reject whitespace-only name (tabs)', () => {
+    expect(() => new SimpleWorkflow('\t\t')).toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  it('should reject whitespace-only name (newlines)', () => {
+    expect(() => new SimpleWorkflow('\n\n')).toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  it('should reject whitespace-only name (mixed whitespace)', () => {
+    expect(() => new SimpleWorkflow('  \t\n  ')).toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  it('should reject name exceeding 100 characters', () => {
+    const longName = 'a'.repeat(101);
+    expect(() => new SimpleWorkflow(longName)).toThrow('Workflow name cannot exceed 100 characters');
+  });
+
+  it('should accept name with exactly 100 characters', () => {
+    const exactly100 = 'a'.repeat(100);
+    const wf = new SimpleWorkflow(exactly100);
+    expect(wf.getNode().name).toBe(exactly100);
+    expect(wf.getNode().name.length).toBe(100);
+  });
+
+  it('should accept valid names with leading/trailing whitespace', () => {
+    const wf1 = new SimpleWorkflow('  MyWorkflow  ');
+    expect(wf1.getNode().name).toBe('  MyWorkflow  ');
+
+    const wf2 = new SimpleWorkflow('\tValidName\t');
+    expect(wf2.getNode().name).toBe('\tValidName\t');
+  });
+
+  it('should use class name when name is undefined', () => {
+    const wf = new SimpleWorkflow();
+    expect(wf.getNode().name).toBe('SimpleWorkflow');
+  });
+
+  it('should use class name when name is null', () => {
+    const wf = new SimpleWorkflow(null as any);
+    expect(wf.getNode().name).toBe('SimpleWorkflow');
+  });
+
+  it('should validate both constructor patterns - class-based with empty name', () => {
+    expect(() => new SimpleWorkflow('')).toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  it('should validate both constructor patterns - functional with empty name', () => {
+    expect(() => new Workflow({ name: '' }, async () => {})).toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  it('should validate both constructor patterns - functional with whitespace name', () => {
+    expect(() => new Workflow({ name: '   ' }, async () => {})).toThrow('Workflow name cannot be empty or whitespace only');
+  });
+
+  it('should validate both constructor patterns - functional with name exceeding 100 characters', () => {
+    const longName = 'a'.repeat(101);
+    expect(() => new Workflow({ name: longName }, async () => {})).toThrow('Workflow name cannot exceed 100 characters');
+  });
+
+  it('should accept valid name in functional pattern', () => {
+    const wf = new Workflow({ name: 'ValidFunctionalWorkflow' }, async () => 'done');
+    expect(wf.getNode().name).toBe('ValidFunctionalWorkflow');
+  });
+});
+
 describe('Workflow', () => {
   it('should create with unique id', () => {
     const wf1 = new SimpleWorkflow();
@@ -78,4 +152,206 @@ describe('Workflow', () => {
     expect(attachEvent).toBeDefined();
     expect(attachEvent?.type === 'childAttached' && attachEvent.parentId).toBe(parent.id);
   });
+
+  it('should capture state and logs in functional workflow error', async () => {
+    // Arrange: Create observer to capture events
+    const events: WorkflowEvent[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: (event) => events.push(event),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    // Arrange: Create functional workflow with a step that throws an error
+    const workflow = new Workflow<void>(
+      { name: 'ErrorCaptureTest' },
+      async (ctx) => {
+        // Execute a step that will fail
+        await ctx.step('failing-step', async () => {
+          throw new Error('Test error from step');
+        });
+      }
+    );
+
+    // Act: Attach observer and run workflow
+    workflow.addObserver(observer);
+    await expect(workflow.run()).rejects.toThrow('Test error from step');
+
+    // Assert: Verify error event was emitted
+    const errorEvents = events.filter((e) => e.type === 'error');
+    expect(errorEvents.length).toBeGreaterThanOrEqual(1);
+
+    // Assert: Verify error structure
+    const errorEvent = errorEvents[0];
+    expect(errorEvent.error).toBeDefined();
+    expect(errorEvent.error.message).toBe('Test error from step');
+
+    // Assert: Verify logs array was captured (even if empty for step errors)
+    expect(errorEvent.error.logs).toBeDefined();
+    expect(Array.isArray(errorEvent.error.logs)).toBe(true);
+
+    // Assert: Verify state was captured (may be empty object for pure functional workflows)
+    expect(errorEvent.error.state).toBeDefined();
+    expect(typeof errorEvent.error.state).toBe('object');
+
+    // Assert: Verify workflow status
+    expect(workflow.status).toBe('failed');
+
+    // Assert: Verify workflowId is captured
+    expect(errorEvent.error.workflowId).toBe(workflow.id);
+  });
+
+  it('should capture @ObservedState fields in workflow error state', async () => {
+    // Test workflow class with @ObservedState decorated fields
+    // Using functional pattern (executor) so error events are emitted via runFunctional()
+    class StatefulWorkflowClass extends Workflow {
+      @ObservedState()
+      stepCount: number = 0;
+
+      @ObservedState({ redact: true })
+      apiKey: string = 'secret-key-123';
+
+      @ObservedState({ hidden: true })
+      internalCounter: number = 42;
+    }
+
+    // Arrange: Create observer to capture error events
+    const events: WorkflowEvent[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: (event) => events.push(event),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    // Arrange: Create workflow with @ObservedState fields using functional pattern
+    const workflow = new StatefulWorkflowClass(
+      { name: 'StatefulErrorTest' },
+      async (ctx) => {
+        // Modify @ObservedState fields on the workflow instance
+        (workflow as any).stepCount = 5;
+        (workflow as any).apiKey = 'updated-key';
+        (workflow as any).internalCounter = 99;
+
+        // Execute a step that will fail
+        await ctx.step('failing-step', async () => {
+          throw new Error('Error after state update');
+        });
+      }
+    );
+
+    // Act: Attach observer and trigger error
+    workflow.addObserver(observer);
+    await expect(workflow.run()).rejects.toThrow('Error after state update');
+
+    // Assert: Verify error event was emitted
+    const errorEvents = events.filter((e) => e.type === 'error');
+    expect(errorEvents.length).toBeGreaterThanOrEqual(1);
+
+    // Assert: Verify error structure
+    const errorEvent = errorEvents[0];
+    expect(errorEvent.error).toBeDefined();
+    expect(errorEvent.error.message).toBe('Error after state update');
+
+    // Assert: Verify @ObservedState fields were captured
+    expect(errorEvent.error.state).toBeDefined();
+    expect(typeof errorEvent.error.state).toBe('object');
+
+    // Assert: Verify public field value is captured
+    expect(errorEvent.error.state.stepCount).toBe(5);
+
+    // Assert: Verify redacted field shows '***'
+    expect(errorEvent.error.state.apiKey).toBe('***');
+
+    // Assert: Verify hidden field is NOT in state
+    expect('internalCounter' in errorEvent.error.state).toBe(false);
+
+    // Assert: Verify logs array is present (may be empty)
+    expect(errorEvent.error.logs).toBeDefined();
+    expect(Array.isArray(errorEvent.error.logs)).toBe(true);
+
+    // Assert: Verify workflow status
+    expect(workflow.status).toBe('failed');
+
+    // Assert: Verify workflowId is captured
+    expect(errorEvent.error.workflowId).toBe(workflow.id);
+  });
+
+  it('should detect circular parent relationship', () => {
+    // Arrange: Create parent and child workflows
+    const parent = new SimpleWorkflow('Parent');
+    const child = new SimpleWorkflow('Child', parent);
+
+    // Act: Create circular reference manually
+    // This simulates a bug or malicious input that creates a cycle
+    parent.parent = child;
+
+    // Assert: getRoot() should throw error for circular reference
+    // Note: getRoot() is protected, so we cast to any to access it
+    expect(() => (parent as any).getRoot()).toThrow(
+      'Circular parent-child relationship detected'
+    );
+  });
+
+  it('should detect circular relationship in getRootObservers', () => {
+    // Arrange: Create parent and child workflows
+    const parent = new SimpleWorkflow('Parent');
+    const child = new SimpleWorkflow('Child', parent);
+
+    // Act: Create circular reference manually
+    // This simulates a bug or malicious input that creates a cycle
+    parent.parent = child;
+
+    // Assert: getRootObservers() should throw error for circular reference
+    // Note: getRootObservers() is private, so we cast to any to access it
+    expect(() => (parent as any).getRootObservers()).toThrow(
+      'Circular parent-child relationship detected'
+    );
+  });
+
+  it('should throw error when duplicate attachment attempted', () => {
+    // Arrange: Create parent and child workflows with first attachment
+    const parent = new SimpleWorkflow('Parent');
+    const child = new SimpleWorkflow('Child', parent);
+
+    // Act & Assert: Second attachment attempt should throw error
+    expect(() => parent.attachChild(child)).toThrow(
+      'Child already attached to this workflow'
+    );
+  });
+
+  it('should emit treeUpdated event when status changes', () => {
+    // Arrange: Create workflow instance
+    const wf = new SimpleWorkflow();
+
+    // Arrange: Create arrays to track event emissions and callback invocations
+    const events: WorkflowEvent[] = [];
+    const treeChangedCalls: WorkflowNode[] = [];
+
+    // Arrange: Create observer with callbacks
+    const observer: WorkflowObserver = {
+      onLog: () => {},  // Empty - not testing logs
+      onEvent: (event) => events.push(event),  // Capture events
+      onStateUpdated: () => {},  // Empty - not testing state updates
+      onTreeChanged: (root) => treeChangedCalls.push(root),  // Capture tree changes
+    };
+
+    // Act: Attach observer and trigger status change
+    wf.addObserver(observer);
+    wf.setStatus('running');
+
+    // Assert: Verify treeUpdated event was emitted
+    const treeUpdatedEvent = events.find((e) => e.type === 'treeUpdated');
+    expect(treeUpdatedEvent).toBeDefined();
+
+    // Assert: Verify event payload contains root node (type narrowing for discriminated union)
+    expect(treeUpdatedEvent?.type === 'treeUpdated' && treeUpdatedEvent.root).toBe(wf.getNode());
+
+    // Assert: Verify onTreeChanged callback was invoked with root node
+    expect(treeChangedCalls).toHaveLength(1);
+    expect(treeChangedCalls[0]).toBe(wf.getNode());
+  });
 });

package/src/core/agent.ts

@@ -63,6 +63,9 @@ export class Agent {
   /** MCP handler for tool management */
   private readonly mcpHandler: MCPHandler;
 
+  /** Direct MCPHandler instances for delegated execution */
+  private readonly mcpHandlers: MCPHandler[] = [];
+
   /** Default model to use */
   private readonly model: string;
 
@@ -87,6 +90,12 @@ export class Agent {
     // Register MCP servers
     if (config.mcps) {
       for (const mcp of config.mcps) {
+        // If the MCP is already an MCPHandler instance, store it directly
+        // for delegated tool execution (preserves registered executors)
+        if (mcp instanceof MCPHandler) {
+          this.mcpHandlers.push(mcp);
+        }
+        // Always register with main handler for tool discovery
         this.mcpHandler.registerServer(mcp);
       }
     }
@@ -463,7 +472,18 @@ export class Agent {
    * Execute a tool (either direct or via MCP)
    */
   private async executeTool(name: string, input: unknown): Promise<unknown> {
-    // Check if it's an MCP tool
+    // First, check stored MCPHandler instances (they have registered executors)
+    for (const handler of this.mcpHandlers) {
+      if (handler.hasTool(name)) {
+        const result = await handler.executeTool(name, input);
+        if (result.is_error) {
+          throw new Error(result.content as string);
+        }
+        return result.content;
+      }
+    }
+
+    // Fall back to main mcpHandler (for non-MCPHandler MCPServers)
     if (this.mcpHandler.hasTool(name)) {
       const result = await this.mcpHandler.executeTool(name, input);
       if (result.is_error) {

package/src/core/logger.ts

@@ -15,6 +15,14 @@ export class WorkflowLogger {
     this.parentLogId = parentLogId;
   }
 
+  /**
+   * Emit a log entry directly to the node without notifying observers
+   * Used to avoid infinite recursion when observer.onLog() throws
+   */
+  private emitWithoutObserverNotification(entry: LogEntry): void {
+    this.node.logs.push(entry);
+  }
+
   /**
    * Emit a log entry to the node and all observers
    */
@@ -24,7 +32,16 @@ export class WorkflowLogger {
       try {
         obs.onLog(entry);
       } catch (err) {
-        console.error('Observer onLog error:', err);
+        // Create error entry and emit without observer notification to avoid infinite recursion
+        const errorEntry: LogEntry = {
+          id: generateId(),
+          workflowId: this.node.id,
+          timestamp: Date.now(),
+          level: 'error',
+          message: 'Observer onLog error',
+          data: { error: err },
+        };
+        this.emitWithoutObserverNotification(errorEntry);
       }
     }
   }
@@ -80,8 +97,16 @@ export class WorkflowLogger {
 
   /**
    * Create a child logger that includes parentLogId
+   * @param parentLogId - ID of the parent log entry (legacy API)
+   */
+  child(parentLogId: string): WorkflowLogger;
+  /**
+   * Create a child logger with metadata
+   * @param meta - Partial log entry metadata (typically { parentLogId: string })
    */
-  child(parentLogId: string): WorkflowLogger {
+  child(meta: Partial<LogEntry>): WorkflowLogger;
+  child(input: string | Partial<LogEntry>): WorkflowLogger {
+    const parentLogId = typeof input === 'string' ? input : input.parentLogId;
     return new WorkflowLogger(this.node, this.observers, parentLogId);
   }
 }

package/src/core/workflow-context.ts

@@ -17,6 +17,7 @@ import type {
   WorkflowEvent,
   ReflectionConfig,
   ReflectionContext,
+  LogEntry,
 } from '../types/index.js';
 import { EventTreeHandleImpl, createEventTreeHandle } from './event-tree.js';
 import {
@@ -26,6 +27,7 @@ import {
 import { generateId } from '../utils/id.js';
 import { ReflectionManager } from '../reflection/reflection.js';
 import { createReflectionConfig } from '../types/index.js';
+import { getObservedState } from '../decorators/observed-state.js';
 
 /**
  * Interface for workflow-like objects that can emit events
@@ -157,8 +159,8 @@ export class WorkflowContextImpl implements WorkflowContext {
             original: error,
             workflowId: this.workflowId,
             stack: error instanceof Error ? error.stack : undefined,
-            state: {},
-            logs: [],
+            state: getObservedState(this.workflow),
+            logs: [...this.workflow.node.logs] as LogEntry[],
           },
         });
 
@@ -321,8 +323,8 @@ export class WorkflowContextImpl implements WorkflowContext {
           original: error,
           workflowId: this.workflowId,
           stack: error instanceof Error ? error.stack : undefined,
-          state: {},
-          logs: [],
+          state: getObservedState(this.workflow),
+          logs: [...this.workflow.node.logs] as LogEntry[],
         },
       });