groundswell 0.0.1

package/src/decorators/step.ts

@@ -0,0 +1,139 @@
+import type { StepOptions, WorkflowError, WorkflowNode, LogEntry, WorkflowEvent } from '../types/index.js';
+import { getObservedState } from './observed-state.js';
+import { runInContext, type AgentExecutionContext } from '../core/context.js';
+import { generateId } from '../utils/id.js';
+
+// Type for workflow-like objects that @Step can decorate methods on
+interface WorkflowLike {
+  id: string;
+  node: WorkflowNode;
+  logger: {
+    info(message: string, data?: unknown): void;
+  };
+  emitEvent(event: WorkflowEvent): void;
+  snapshotState(): void;
+}
+
+/**
+ * @Step decorator
+ * Wraps a method to emit step events, handle errors, and optionally snapshot state
+ *
+ * @example
+ * class MyWorkflow extends Workflow {
+ *   @Step({ snapshotState: true, trackTiming: true })
+ *   async processData() {
+ *     // ... step logic
+ *   }
+ * }
+ */
+export function Step(opts: StepOptions = {}) {
+  return function <This, Args extends unknown[], Return>(
+    originalMethod: (this: This, ...args: Args) => Promise<Return>,
+    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>
+  ) {
+    const methodName = String(context.name);
+
+    // CRITICAL: Use regular function, not arrow function, to preserve 'this'
+    async function stepWrapper(this: This, ...args: Args): Promise<Return> {
+      // Cast to WorkflowLike for type safety when accessing workflow properties
+      const wf = this as unknown as WorkflowLike;
+      const stepName = opts.name ?? methodName;
+      const startTime = Date.now();
+
+      // Log start if requested
+      if (opts.logStart) {
+        wf.logger.info(`STEP START: ${stepName}`);
+      }
+
+      // Emit step start event
+      wf.emitEvent({
+        type: 'stepStart',
+        node: wf.node,
+        step: stepName,
+      });
+
+      // Create step node for hierarchy tracking
+      const stepNode: WorkflowNode = {
+        id: generateId(),
+        name: stepName,
+        parent: wf.node,
+        children: [],
+        status: 'running',
+        logs: [],
+        events: [],
+        stateSnapshot: null,
+      };
+
+      // Create execution context for agent/prompt operations within this step
+      const executionContext: AgentExecutionContext = {
+        workflowNode: stepNode,
+        emitEvent: (event: WorkflowEvent) => {
+          stepNode.events.push(event);
+          wf.emitEvent(event);
+        },
+        workflowId: wf.id,
+      };
+
+      try {
+        // Execute the original method within the execution context
+        // This allows Agent.prompt() calls to automatically capture events
+        const result = await runInContext(executionContext, async () => {
+          return originalMethod.call(this, ...args);
+        });
+
+        // Update step node status
+        stepNode.status = 'completed';
+
+        // Snapshot state if requested
+        if (opts.snapshotState) {
+          wf.snapshotState();
+        }
+
+        // Calculate duration and emit end event
+        const duration = Date.now() - startTime;
+        if (opts.trackTiming !== false) {
+          wf.emitEvent({
+            type: 'stepEnd',
+            node: wf.node,
+            step: stepName,
+            duration,
+          });
+        }
+
+        // Log finish if requested
+        if (opts.logFinish) {
+          wf.logger.info(`STEP END: ${stepName} (${duration}ms)`);
+        }
+
+        return result;
+      } catch (err: unknown) {
+        // Update step node status
+        stepNode.status = 'failed';
+        // Create rich error with context
+        const error = err as Error;
+        const snap = getObservedState(this as object);
+
+        const workflowError: WorkflowError = {
+          message: error?.message ?? 'Unknown error',
+          original: err,
+          workflowId: wf.id,
+          stack: error?.stack,
+          state: snap,
+          logs: [...wf.node.logs] as LogEntry[],
+        };
+
+        // Emit error event
+        wf.emitEvent({
+          type: 'error',
+          node: wf.node,
+          error: workflowError,
+        });
+
+        // Re-throw the enriched error
+        throw workflowError;
+      }
+    }
+
+    return stepWrapper;
+  };
+}

package/src/decorators/task.ts

@@ -0,0 +1,96 @@
+import type { TaskOptions, WorkflowNode, WorkflowEvent } from '../types/index.js';
+
+// Type for workflow-like objects
+interface WorkflowLike {
+  id: string;
+  node: WorkflowNode;
+  emitEvent(event: WorkflowEvent): void;
+  attachChild(child: WorkflowLike): void;
+}
+
+// Minimal Workflow type for checking if something is a workflow
+interface WorkflowClass {
+  id: string;
+  parent: WorkflowLike | null;
+  run(...args: unknown[]): Promise<unknown>;
+}
+
+/**
+ * @Task decorator
+ * Wraps a method that returns child workflow(s), automatically attaching them
+ *
+ * @example
+ * class ParentWorkflow extends Workflow {
+ *   @Task({ concurrent: true })
+ *   async createChildren(): Promise<ChildWorkflow[]> {
+ *     return [
+ *       new ChildWorkflow('child1', this),
+ *       new ChildWorkflow('child2', this),
+ *     ];
+ *   }
+ * }
+ */
+export function Task(opts: TaskOptions = {}) {
+  return function <This, Args extends unknown[], Return>(
+    originalMethod: (this: This, ...args: Args) => Promise<Return>,
+    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>
+  ) {
+    const methodName = String(context.name);
+
+    // CRITICAL: Use regular function, not arrow function
+    async function taskWrapper(this: This, ...args: Args): Promise<Return> {
+      // Cast to WorkflowLike for type safety when accessing workflow properties
+      const wf = this as unknown as WorkflowLike;
+      const taskName = opts.name ?? methodName;
+
+      // Emit task start event
+      wf.emitEvent({
+        type: 'taskStart',
+        node: wf.node,
+        task: taskName,
+      });
+
+      // Execute the original method
+      const result = await originalMethod.call(this, ...args);
+
+      // Process returned workflows
+      const workflows = Array.isArray(result) ? result : [result];
+
+      for (const workflow of workflows) {
+        // Type guard to check if it's a workflow
+        if (workflow && typeof workflow === 'object' && 'id' in workflow) {
+          const childWf = workflow as WorkflowClass;
+
+          // Only attach if not already attached (parent not set by constructor)
+          if (!childWf.parent) {
+            childWf.parent = wf;
+            wf.attachChild(childWf as unknown as WorkflowLike);
+          }
+        }
+      }
+
+      // If concurrent option is set and we have multiple workflows, run them in parallel
+      if (opts.concurrent && Array.isArray(result)) {
+        const runnable = workflows.filter(
+          (w): w is WorkflowClass =>
+            w && typeof w === 'object' && 'run' in w && typeof w.run === 'function'
+        );
+
+        if (runnable.length > 0) {
+          await Promise.all(runnable.map((w) => w.run()));
+        }
+      }
+
+      // Emit task end event
+      wf.emitEvent({
+        type: 'taskEnd',
+        node: wf.node,
+        task: taskName,
+      });
+
+      return result;
+    }
+
+    return taskWrapper;
+  };
+}

package/src/examples/index.ts

@@ -0,0 +1,2 @@
+export { TestCycleWorkflow } from './test-cycle-workflow.js';
+export { TDDOrchestrator } from './tdd-orchestrator.js';

package/src/examples/tdd-orchestrator.ts

@@ -0,0 +1,65 @@
+import { Workflow } from '../core/workflow.js';
+import { Step } from '../decorators/step.js';
+import { Task } from '../decorators/task.js';
+import { ObservedState } from '../decorators/observed-state.js';
+import { TestCycleWorkflow } from './test-cycle-workflow.js';
+
+/**
+ * Example parent workflow demonstrating TDD orchestration
+ */
+export class TDDOrchestrator extends Workflow {
+  @ObservedState()
+  cycleCount: number = 0;
+
+  @ObservedState()
+  maxCycles: number = 3;
+
+  @ObservedState({ redact: true })
+  apiKey: string = 'secret-key';
+
+  @Step({ logStart: true, logFinish: true })
+  async setupEnvironment(): Promise<void> {
+    this.logger.info('Setting up TDD environment');
+    // Simulate environment setup
+    await this.delay(50);
+    this.logger.debug('Environment ready');
+  }
+
+  @Task()
+  async runCycle(): Promise<TestCycleWorkflow> {
+    this.cycleCount++;
+    this.logger.info(`Starting cycle ${this.cycleCount}/${this.maxCycles}`);
+    return new TestCycleWorkflow(`Cycle-${this.cycleCount}`, this);
+  }
+
+  async run(): Promise<void> {
+    this.setStatus('running');
+    this.logger.info('TDD Orchestrator starting');
+
+    try {
+      await this.setupEnvironment();
+
+      while (this.cycleCount < this.maxCycles) {
+        try {
+          const cycle = await this.runCycle();
+          await cycle.run();
+          this.logger.info(`Cycle ${this.cycleCount} completed successfully`);
+        } catch (error) {
+          this.logger.warn(`Cycle ${this.cycleCount} failed, continuing...`);
+          // In real implementation, analyze error and potentially restart
+        }
+      }
+
+      this.setStatus('completed');
+      this.logger.info('TDD Orchestrator completed all cycles');
+    } catch (error) {
+      this.setStatus('failed');
+      this.logger.error('TDD Orchestrator failed', { error });
+      throw error;
+    }
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/examples/test-cycle-workflow.ts

@@ -0,0 +1,64 @@
+import { Workflow } from '../core/workflow.js';
+import { Step } from '../decorators/step.js';
+import { ObservedState } from '../decorators/observed-state.js';
+
+/**
+ * Example child workflow demonstrating test cycle
+ */
+export class TestCycleWorkflow extends Workflow {
+  @ObservedState()
+  currentTest: string = '';
+
+  @ObservedState()
+  testResult: 'pending' | 'passed' | 'failed' = 'pending';
+
+  @Step({ snapshotState: true, trackTiming: true, logStart: true })
+  async generateTest(): Promise<string> {
+    this.logger.info('Generating test case');
+    this.currentTest = `test_${Date.now()}`;
+    // Simulate test generation
+    await this.delay(100);
+    return this.currentTest;
+  }
+
+  @Step({ trackTiming: true })
+  async runTest(): Promise<boolean> {
+    this.logger.info(`Running test: ${this.currentTest}`);
+    // Simulate test execution
+    await this.delay(200);
+
+    // Randomly pass or fail for demonstration
+    const passed = Math.random() > 0.3;
+    this.testResult = passed ? 'passed' : 'failed';
+
+    if (!passed) {
+      throw new Error(`Test ${this.currentTest} failed`);
+    }
+
+    return true;
+  }
+
+  @Step({ snapshotState: true })
+  async updateImplementation(): Promise<void> {
+    this.logger.info('Updating implementation based on test results');
+    await this.delay(150);
+  }
+
+  async run(): Promise<void> {
+    this.setStatus('running');
+
+    try {
+      await this.generateTest();
+      await this.runTest();
+      await this.updateImplementation();
+      this.setStatus('completed');
+    } catch (error) {
+      this.setStatus('failed');
+      throw error;
+    }
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/index.ts

@@ -0,0 +1,140 @@
+// Types
+export type {
+  WorkflowStatus,
+  WorkflowNode,
+  LogLevel,
+  LogEntry,
+  SerializedWorkflowState,
+  StateFieldMetadata,
+  WorkflowError,
+  WorkflowEvent,
+  WorkflowObserver,
+  StepOptions,
+  TaskOptions,
+  ErrorMergeStrategy,
+  // SDK primitive types
+  Tool,
+  ToolResult,
+  MCPServer,
+  Skill,
+  HookHandler,
+  PreToolUseContext,
+  PostToolUseContext,
+  SessionStartContext,
+  SessionEndContext,
+  AgentHooks,
+  TokenUsage,
+  // Agent and Prompt types
+  AgentConfig,
+  PromptOverrides,
+  PromptConfig,
+  // WorkflowContext types
+  WorkflowContext,
+  WorkflowConfig,
+  WorkflowResult,
+  EventTreeHandle,
+  EventNode,
+  EventMetrics,
+  AgentLike,
+  PromptLike,
+  // Reflection types
+  ReflectionAPI,
+  ReflectionConfig,
+  ReflectionContext,
+  ReflectionResult,
+  ReflectionEntry,
+} from './types/index.js';
+
+// Re-export reflection utilities
+export {
+  DEFAULT_REFLECTION_CONFIG,
+  createReflectionConfig,
+} from './types/index.js';
+
+// Core classes
+export { Workflow, type WorkflowExecutor } from './core/workflow.js';
+export { WorkflowLogger } from './core/logger.js';
+export { Agent, type PromptResult } from './core/agent.js';
+export { Prompt } from './core/prompt.js';
+export { MCPHandler, type ToolExecutor } from './core/mcp-handler.js';
+
+// Context and event tree
+export { EventTreeHandleImpl, createEventTreeHandle } from './core/event-tree.js';
+export { WorkflowContextImpl, createWorkflowContext } from './core/workflow-context.js';
+export {
+  getExecutionContext,
+  requireExecutionContext,
+  runInContext,
+  runInContextSync,
+  hasExecutionContext,
+  createChildContext,
+  agentExecutionStorage,
+  type AgentExecutionContext,
+} from './core/context.js';
+
+// Decorators
+export { Step } from './decorators/step.js';
+export { Task } from './decorators/task.js';
+export { ObservedState, getObservedState } from './decorators/observed-state.js';
+
+// Debugger
+export { WorkflowTreeDebugger } from './debugger/tree-debugger.js';
+
+// Utilities
+export { Observable } from './utils/observable.js';
+export type { Subscription, Observer } from './utils/observable.js';
+export { generateId } from './utils/id.js';
+
+// Factory functions
+export {
+  createWorkflow,
+  createAgent,
+  createPrompt,
+  quickWorkflow,
+  quickAgent,
+} from './core/factory.js';
+
+// Cache
+export { LLMCache, defaultCache } from './cache/cache.js';
+export { generateCacheKey, deterministicStringify, getSchemaHash } from './cache/cache-key.js';
+export type { CacheConfig, CacheMetrics } from './cache/cache.js';
+export type { CacheKeyInputs } from './cache/cache-key.js';
+
+// Reflection
+export { ReflectionManager, executeWithReflection } from './reflection/reflection.js';
+
+// Introspection Tools
+export {
+  INTROSPECTION_TOOLS,
+  INTROSPECTION_HANDLERS,
+  registerIntrospectionTools,
+  executeIntrospectionTool,
+  // Individual tools
+  inspectCurrentNodeTool,
+  readAncestorChainTool,
+  listSiblingsChildrenTool,
+  inspectPriorOutputsTool,
+  inspectCacheStatusTool,
+  requestSpawnWorkflowTool,
+  // Handlers
+  handleInspectCurrentNode,
+  handleReadAncestorChain,
+  handleListSiblingsChildren,
+  handleInspectPriorOutputs,
+  handleInspectCacheStatus,
+  handleRequestSpawnWorkflow,
+} from './tools/introspection.js';
+export type {
+  CurrentNodeInfo,
+  AncestorInfo,
+  AncestorChainResult,
+  NodeInfo,
+  SiblingsChildrenResult,
+  PriorOutputInfo,
+  CacheStatusResult,
+  SpawnWorkflowRequest,
+} from './tools/introspection.js';
+
+// Examples (for reference)
+export { TestCycleWorkflow } from './examples/test-cycle-workflow.js';
+export { TDDOrchestrator } from './examples/tdd-orchestrator.js';

package/src/reflection/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Reflection module exports
+ */
+
+export { ReflectionManager, executeWithReflection } from './reflection.js';