groundswell 0.0.2 → 1.0.0

package/examples/README.md

@@ -1,258 +0,0 @@
-# Groundswell Workflow Engine - Examples
-
-Comprehensive examples showcasing all features and configuration options of the Groundswell hierarchical workflow engine.
-
-## Quick Start
-
-```bash
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run all examples
-npm run start:all
-
-# Or run individual examples
-npm run start:basic
-npm run start:decorators
-npm run start:parent-child
-npm run start:observers
-npm run start:errors
-npm run start:concurrent
-npm run start:agent-loops
-npm run start:sdk-features
-npm run start:reflection
-npm run start:introspection
-npm run start:reparenting
-```
-
-## Examples Overview
-
-### 1. Basic Workflow (`01-basic-workflow.ts`)
-
-Core workflow concepts:
-- Creating workflows by extending `Workflow` base class
-- Using `WorkflowLogger` for structured logging
-- Managing workflow status (`idle` → `running` → `completed`/`failed`)
-- Using `WorkflowTreeDebugger` for visualization
-
-### 2. Decorator Options (`02-decorator-options.ts`)
-
-All decorator configuration options:
-
-**@Step options:**
-- `name` - Custom step name (defaults to method name)
-- `snapshotState` - Capture state after step completion
-- `trackTiming` - Track and emit step duration
-- `logStart` - Log message at step start
-- `logFinish` - Log message at step end
-
-**@Task options:**
-- `name` - Custom task name
-- `concurrent` - Run returned workflows concurrently
-
-**@ObservedState options:**
-- `hidden` - Exclude from state snapshots
-- `redact` - Show as `***` in snapshots (for sensitive data)
-
-### 3. Parent-Child Workflows (`03-parent-child.ts`)
-
-Hierarchical workflow structures:
-- Multi-level workflow hierarchies
-- Automatic parent-child attachment
-- `@Task` decorator for spawning child workflows
-- Event propagation from children to root
-- Tree visualization of nested structures
-
-### 4. Observers & Debugger (`04-observers-debugger.ts`)
-
-Real-time monitoring and debugging:
-- Implementing custom `WorkflowObserver`
-- `MetricsObserver` for collecting statistics
-- `ConsoleObserver` for real-time logging
-- `Observable` event stream subscription
-- `WorkflowTreeDebugger` complete API
-
-### 5. Error Handling (`05-error-handling.ts`)
-
-Error management patterns:
-- `WorkflowError` structure with full context
-- State snapshots preserved at error time
-- Error events emitted to observers
-- Retry patterns with backoff
-- Error isolation in parent-child workflows
-
-### 6. Concurrent Tasks (`06-concurrent-tasks.ts`)
-
-Parallel execution patterns:
-- Sequential vs concurrent comparison
-- `@Task({ concurrent: true })` option
-- Manual `Promise.all` patterns
-- Fan-out / fan-in architecture
-- Performance benchmarks
-
-### 7. Agent Loops with Observability (`07-agent-loops.ts`)
-
-Run: `npx tsx examples/examples/07-agent-loops.ts`
-
-Agent.prompt() within workflow loops:
-- Using Agent.prompt() within ctx.step() loops
-- Multiple agents for different item types
-- Full event tree visualization with timing
-- State snapshots at each iteration
-- Cache hit/miss tracking
-
-### 8. SDK Features Integration (`08-sdk-features.ts`)
-
-Run: `npx tsx examples/examples/08-sdk-features.ts`
-
-Anthropic SDK integration:
-- Custom tool definitions with handlers
-- MCP server configuration (inprocess)
-- Pre/Post tool hooks for logging and validation
-- Skills integration with system prompt content
-- Environment variable pass-through
-
-### 9. Multi-level Reflection (`09-reflection.ts`)
-
-Run: `npx tsx examples/examples/09-reflection.ts`
-
-Reflection at all three levels:
-- Prompt-level reflection (enableReflection on prompt)
-- Agent-level reflection (agent.reflect() method)
-- Workflow-level reflection (step failure retry)
-- Reflection events in tree output
-- Error recovery with revised prompts
-
-### 10. Introspection Tools Demo (`10-introspection.ts`)
-
-Run: `npx tsx examples/examples/10-introspection.ts`
-
-Agent self-awareness and hierarchy navigation:
-- inspect_current_node - "Where am I?"
-- read_ancestor_chain - "What's above me?"
-- list_siblings_children - "What's around me?"
-- inspect_prior_outputs - "What happened before?"
-- inspect_cache_status - "Is this cached?"
-- request_spawn_workflow - "Can I create children?"
-
-### 11. Reparenting Workflows (`11-reparenting-workflows.ts`)
-
-Run: `npx tsx examples/examples/11-reparenting-workflows.ts`
-
-Workflow reparenting with detach-then-attach pattern:
-- WRONG way: Direct attachChild() throws error (single-parent invariant)
-- RIGHT way: detachChild() then attachChild() pattern
-- Tree structure verification before/after reparenting
-- Observer propagation updates after reparenting
-- Dual-tree synchronization (workflow tree + node tree)
-- Error handling for invalid reparenting operations
-
-## Project Structure
-
-```
-examples/
-├── examples/
-│   ├── 01-basic-workflow.ts
-│   ├── 02-decorator-options.ts
-│   ├── 03-parent-child.ts
-│   ├── 04-observers-debugger.ts
-│   ├── 05-error-handling.ts
-│   ├── 06-concurrent-tasks.ts
-│   ├── 07-agent-loops.ts
-│   ├── 08-sdk-features.ts
-│   ├── 09-reflection.ts
-│   ├── 10-introspection.ts
-│   └── 11-reparenting-workflows.ts
-├── utils/
-│   └── helpers.ts
-├── index.ts
-└── README.md
-```
-
-## Key Concepts
-
-### Workflow Status Lifecycle
-
-```
-idle → running → completed
-                ↘ failed
-                ↘ cancelled
-```
-
-### Event Types
-
-| Event Type | Description |
-|------------|-------------|
-| `stepStart` | Step execution started |
-| `stepEnd` | Step completed (includes duration) |
-| `taskStart` | Task execution started |
-| `taskEnd` | Task completed |
-| `childAttached` | Child workflow attached to parent |
-| `stateSnapshot` | State snapshot captured |
-| `error` | Error occurred |
-| `treeUpdated` | Tree structure changed |
-
-### Tree Visualization Symbols
-
-| Symbol | Status |
-|--------|--------|
-| ○ | idle |
-| ◐ | running |
-| ✓ | completed |
-| ✗ | failed |
-| ⊘ | cancelled |
-
-## Usage Patterns
-
-### Basic Workflow
-```typescript
-class MyWorkflow extends Workflow {
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.logger.info('Starting workflow');
-    // ... workflow logic
-    this.setStatus('completed');
-  }
-}
-```
-
-### Step with All Options
-```typescript
-@Step({
-  name: 'CustomStepName',
-  snapshotState: true,
-  trackTiming: true,
-  logStart: true,
-  logFinish: true,
-})
-async myStep(): Promise<void> {
-  // Step logic
-}
-```
-
-### Observable State
-```typescript
-@ObservedState()
-publicField: string = 'visible';
-
-@ObservedState({ redact: true })
-apiKey: string = 'secret';
-
-@ObservedState({ hidden: true })
-internalState: object = {};
-```
-
-### Concurrent Child Workflows
-```typescript
-@Task({ concurrent: true })
-async createWorkers(): Promise<WorkerWorkflow[]> {
-  return items.map(item => new WorkerWorkflow(item, this));
-}
-```
-
-## License
-
-MIT

package/examples/examples/01-basic-workflow.ts

@@ -1,100 +0,0 @@
-/**
- * Example 1: Basic Workflow
- *
- * Demonstrates:
- * - Creating a simple workflow by extending the Workflow base class
- * - Using the logger for structured logging
- * - Managing workflow status (idle -> running -> completed/failed)
- * - Basic execution flow
- */
-
-import { Workflow, WorkflowTreeDebugger } from 'groundswell';
-import { printHeader, printSection, sleep } from '../utils/helpers.js';
-
-/**
- * A simple data processing workflow
- */
-class DataProcessingWorkflow extends Workflow {
-  private data: string[] = [];
-
-  async run(): Promise<string[]> {
-    this.setStatus('running');
-    this.logger.info('Starting data processing workflow');
-
-    try {
-      // Step 1: Load data
-      this.logger.info('Loading data...');
-      await this.loadData();
-
-      // Step 2: Process data
-      this.logger.info('Processing data...');
-      await this.processData();
-
-      // Step 3: Save results
-      this.logger.info('Saving results...');
-      await this.saveResults();
-
-      this.setStatus('completed');
-      this.logger.info('Workflow completed successfully');
-      return this.data;
-    } catch (error) {
-      this.setStatus('failed');
-      this.logger.error('Workflow failed', { error });
-      throw error;
-    }
-  }
-
-  private async loadData(): Promise<void> {
-    await sleep(100);
-    this.data = ['item1', 'item2', 'item3'];
-    this.logger.debug('Loaded items', { count: this.data.length });
-  }
-
-  private async processData(): Promise<void> {
-    await sleep(150);
-    this.data = this.data.map((item) => item.toUpperCase());
-    this.logger.debug('Processed items', { data: this.data });
-  }
-
-  private async saveResults(): Promise<void> {
-    await sleep(50);
-    this.logger.debug('Results saved');
-  }
-}
-
-/**
- * Run the basic workflow example
- */
-export async function runBasicWorkflowExample(): Promise<void> {
-  printHeader('Example 1: Basic Workflow');
-
-  // Create workflow with custom name
-  const workflow = new DataProcessingWorkflow('DataProcessor');
-
-  // Attach debugger to visualize
-  const debugger_ = new WorkflowTreeDebugger(workflow);
-
-  printSection('Initial State');
-  console.log('Workflow ID:', workflow.id);
-  console.log('Status:', workflow.status);
-  console.log('Tree:\n' + debugger_.toTreeString());
-
-  printSection('Running Workflow');
-  const result = await workflow.run();
-
-  printSection('Final State');
-  console.log('Status:', workflow.status);
-  console.log('Result:', result);
-  console.log('\nTree:\n' + debugger_.toTreeString());
-
-  printSection('Logs');
-  console.log(debugger_.toLogString());
-
-  printSection('Statistics');
-  console.log(debugger_.getStats());
-}
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runBasicWorkflowExample().catch(console.error);
-}

package/examples/examples/02-decorator-options.ts

@@ -1,217 +0,0 @@
-/**
- * Example 2: Decorator Options
- *
- * Demonstrates all decorator configuration options:
- *
- * @Step options:
- * - name: Custom step name (defaults to method name)
- * - snapshotState: Capture state snapshot after step completion
- * - trackTiming: Track and emit step duration
- * - logStart: Log message at step start
- * - logFinish: Log message at step end
- *
- * @Task options:
- * - name: Custom task name
- * - concurrent: Run returned workflows concurrently
- *
- * @ObservedState options:
- * - hidden: Field not included in snapshots
- * - redact: Value shown as '***' in snapshots
- */
-
-import {
-  Workflow,
-  Step,
-  Task,
-  ObservedState,
-  getObservedState,
-  WorkflowTreeDebugger,
-  WorkflowObserver,
-  WorkflowEvent,
-  LogEntry,
-  WorkflowNode,
-} from 'groundswell';
-import { printHeader, printSection, sleep } from '../utils/helpers.js';
-
-/**
- * Workflow demonstrating all @Step decorator options
- */
-class StepOptionsWorkflow extends Workflow {
-  @ObservedState()
-  currentPhase: string = 'init';
-
-  @ObservedState()
-  itemsProcessed: number = 0;
-
-  // Default step - minimal configuration
-  @Step()
-  async defaultStep(): Promise<void> {
-    this.currentPhase = 'default';
-    await sleep(50);
-  }
-
-  // Step with custom name
-  @Step({ name: 'CustomNamedStep' })
-  async stepWithCustomName(): Promise<void> {
-    this.currentPhase = 'custom-named';
-    await sleep(50);
-  }
-
-  // Step with state snapshot
-  @Step({ snapshotState: true })
-  async stepWithSnapshot(): Promise<void> {
-    this.currentPhase = 'snapshot';
-    this.itemsProcessed = 10;
-    await sleep(50);
-    // State will be captured after this step
-  }
-
-  // Step with timing tracking
-  @Step({ trackTiming: true })
-  async stepWithTiming(): Promise<void> {
-    this.currentPhase = 'timed';
-    await sleep(200); // Longer delay to show timing
-  }
-
-  // Step with start/finish logging
-  @Step({ logStart: true, logFinish: true })
-  async stepWithLogging(): Promise<void> {
-    this.currentPhase = 'logged';
-    this.logger.info('Inside the step - this is custom logging');
-    await sleep(50);
-  }
-
-  // Step with ALL options enabled
-  @Step({
-    name: 'FullyConfiguredStep',
-    snapshotState: true,
-    trackTiming: true,
-    logStart: true,
-    logFinish: true,
-  })
-  async fullyConfiguredStep(): Promise<void> {
-    this.currentPhase = 'fully-configured';
-    this.itemsProcessed = 100;
-    await sleep(100);
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-
-    await this.defaultStep();
-    await this.stepWithCustomName();
-    await this.stepWithSnapshot();
-    await this.stepWithTiming();
-    await this.stepWithLogging();
-    await this.fullyConfiguredStep();
-
-    this.setStatus('completed');
-  }
-}
-
-/**
- * Workflow demonstrating @ObservedState options
- */
-class StateOptionsWorkflow extends Workflow {
-  // Regular observed state - included in snapshots
-  @ObservedState()
-  publicData: string = 'visible-value';
-
-  // Redacted state - shows as '***' in snapshots
-  @ObservedState({ redact: true })
-  apiKey: string = 'super-secret-api-key-12345';
-
-  // Another redacted field
-  @ObservedState({ redact: true })
-  password: string = 'my-password';
-
-  // Hidden state - completely excluded from snapshots
-  @ObservedState({ hidden: true })
-  internalCounter: number = 0;
-
-  // Another hidden field
-  @ObservedState({ hidden: true })
-  debugInfo: object = { internal: true };
-
-  // Multiple observed fields for demonstration
-  @ObservedState()
-  processingStatus: string = 'pending';
-
-  @ObservedState()
-  progress: number = 0;
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.processingStatus = 'processing';
-    this.progress = 50;
-    this.internalCounter = 999; // This won't appear in snapshots
-    await sleep(50);
-    this.processingStatus = 'done';
-    this.progress = 100;
-    this.setStatus('completed');
-  }
-}
-
-/**
- * Run the decorator options example
- */
-export async function runDecoratorOptionsExample(): Promise<void> {
-  printHeader('Example 2: Decorator Options');
-
-  // Part 1: @Step options
-  printSection('@Step Decorator Options');
-
-  const stepWorkflow = new StepOptionsWorkflow('StepOptions');
-  const events: WorkflowEvent[] = [];
-
-  // Custom observer to capture events
-  const observer: WorkflowObserver = {
-    onLog: (entry: LogEntry) => {
-      console.log(`  [LOG] ${entry.level.toUpperCase()}: ${entry.message}`);
-    },
-    onEvent: (event: WorkflowEvent) => {
-      events.push(event);
-      if (event.type === 'stepStart') {
-        console.log(`  [EVENT] Step started: ${event.step}`);
-      } else if (event.type === 'stepEnd') {
-        console.log(`  [EVENT] Step ended: ${event.step} (${event.duration}ms)`);
-      } else if (event.type === 'stateSnapshot') {
-        console.log(`  [EVENT] State snapshot captured`);
-      }
-    },
-    onStateUpdated: () => {},
-    onTreeChanged: () => {},
-  };
-
-  stepWorkflow.addObserver(observer);
-  await stepWorkflow.run();
-
-  console.log('\nStep events captured:', events.filter((e) => e.type.includes('step')).length);
-
-  // Part 2: @ObservedState options
-  printSection('@ObservedState Decorator Options');
-
-  const stateWorkflow = new StateOptionsWorkflow('StateOptions');
-  await stateWorkflow.run();
-
-  console.log('Actual field values:');
-  console.log('  publicData:', stateWorkflow.publicData);
-  console.log('  apiKey:', stateWorkflow.apiKey);
-  console.log('  password:', stateWorkflow.password);
-  console.log('  internalCounter:', (stateWorkflow as any).internalCounter);
-  console.log('  processingStatus:', stateWorkflow.processingStatus);
-  console.log('  progress:', stateWorkflow.progress);
-
-  console.log('\nState snapshot (via getObservedState):');
-  const snapshot = getObservedState(stateWorkflow);
-  console.log(JSON.stringify(snapshot, null, 2));
-
-  console.log('\nNote:');
-  console.log('  - apiKey and password show as "***" (redacted)');
-  console.log('  - internalCounter and debugInfo are not present (hidden)');
-}
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runDecoratorOptionsExample().catch(console.error);
-}