groundswell 0.0.1

package/examples/README.md

@@ -0,0 +1,244 @@
+# 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
+```
+
+## 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?"
+
+## 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
+├── 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

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

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