groundswell 0.0.1 → 0.0.3

package/src/core/workflow-context.ts

@@ -1,349 +0,0 @@
-/**
- * WorkflowContextImpl - Implementation of functional workflow context
- *
- * Provides step(), spawnWorkflow(), and automatic context propagation
- * for agents and prompts executed within workflows.
- */
-
-import type {
-  WorkflowContext,
-  EventTreeHandle,
-  ReflectionAPI,
-  AgentLike,
-  PromptLike,
-} from '../types/workflow-context.js';
-import type {
-  WorkflowNode,
-  WorkflowEvent,
-  ReflectionConfig,
-  ReflectionContext,
-} from '../types/index.js';
-import { EventTreeHandleImpl, createEventTreeHandle } from './event-tree.js';
-import {
-  runInContext,
-  type AgentExecutionContext,
-} from './context.js';
-import { generateId } from '../utils/id.js';
-import { ReflectionManager } from '../reflection/reflection.js';
-import { createReflectionConfig } from '../types/index.js';
-
-/**
- * Interface for workflow-like objects that can emit events
- */
-interface WorkflowLike {
-  id: string;
-  node: WorkflowNode;
-  emitEvent(event: WorkflowEvent): void;
-  setStatus(status: 'idle' | 'running' | 'completed' | 'failed' | 'cancelled'): void;
-  attachChild(child: WorkflowLike): void;
-}
-
-/**
- * WorkflowContext implementation
- */
-export class WorkflowContextImpl implements WorkflowContext {
-  public readonly workflowId: string;
-  public readonly parentWorkflowId?: string;
-  public readonly eventTree: EventTreeHandle;
-  public readonly reflection: ReflectionAPI;
-
-  private workflow: WorkflowLike;
-  private eventTreeImpl: EventTreeHandleImpl;
-  private reflectionManager: ReflectionManager;
-
-  constructor(
-    workflow: WorkflowLike,
-    parentWorkflowId?: string,
-    reflectionConfig?: Partial<ReflectionConfig>
-  ) {
-    this.workflowId = workflow.id;
-    this.parentWorkflowId = parentWorkflowId;
-    this.workflow = workflow;
-
-    // Create event tree handle
-    this.eventTreeImpl = new EventTreeHandleImpl(workflow.node);
-    this.eventTree = this.eventTreeImpl;
-
-    // Create reflection manager with config
-    const config = createReflectionConfig(reflectionConfig);
-    this.reflectionManager = new ReflectionManager(config);
-    this.reflectionManager.setEventEmitter((event) => this.workflow.emitEvent(event));
-    this.reflection = this.reflectionManager;
-  }
-
-  /**
-   * Execute a named step with automatic context propagation and reflection support
-   */
-  async step<T>(name: string, fn: () => Promise<T>): Promise<T> {
-    const maxAttempts = this.reflectionManager.isEnabled()
-      ? this.reflectionManager.getMaxAttempts()
-      : 1;
-
-    let lastError: Error | null = null;
-
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      const startTime = Date.now();
-
-      // Create step node
-      const stepNode: WorkflowNode = {
-        id: generateId(),
-        name: attempt > 1 ? `${name} (retry ${attempt - 1})` : name,
-        parent: this.workflow.node,
-        children: [],
-        status: 'running',
-        logs: [],
-        events: [],
-        stateSnapshot: null,
-      };
-
-      // Attach to parent
-      this.workflow.node.children.push(stepNode);
-
-      // Emit step start
-      this.workflow.emitEvent({
-        type: 'stepStart',
-        node: stepNode,
-        step: name,
-      });
-
-      // Create execution context for this step
-      const executionContext: AgentExecutionContext = {
-        workflowNode: stepNode,
-        emitEvent: (event: WorkflowEvent) => {
-          stepNode.events.push(event);
-          this.workflow.emitEvent(event);
-        },
-        workflowId: this.workflowId,
-        parentWorkflowId: this.parentWorkflowId,
-      };
-
-      try {
-        // Execute function in context
-        const result = await runInContext(executionContext, fn);
-
-        // Update step node status
-        stepNode.status = 'completed';
-
-        // Emit step end
-        const duration = Date.now() - startTime;
-        this.workflow.emitEvent({
-          type: 'stepEnd',
-          node: stepNode,
-          step: name,
-          duration,
-        });
-
-        // Rebuild event tree
-        this.eventTreeImpl.rebuild(this.workflow.node);
-
-        // If we succeeded after a reflection, mark it as successful
-        if (attempt > 1) {
-          this.reflectionManager.markLastReflectionSuccessful();
-        }
-
-        return result;
-      } catch (error) {
-        lastError = error as Error;
-
-        // Update step node status
-        stepNode.status = 'failed';
-
-        // Emit error event
-        this.workflow.emitEvent({
-          type: 'error',
-          node: stepNode,
-          error: {
-            message: error instanceof Error ? error.message : 'Unknown error',
-            original: error,
-            workflowId: this.workflowId,
-            stack: error instanceof Error ? error.stack : undefined,
-            state: {},
-            logs: [],
-          },
-        });
-
-        // Rebuild event tree
-        this.eventTreeImpl.rebuild(this.workflow.node);
-
-        // Check if we should try reflection
-        if (!this.reflectionManager.isEnabled() || attempt === maxAttempts) {
-          throw error;
-        }
-
-        // Try reflection
-        const reflectionContext: ReflectionContext = {
-          level: 'workflow',
-          failedNode: stepNode,
-          error: lastError,
-          attemptNumber: attempt,
-          previousAttempts: this.reflectionManager.getReflectionHistory(),
-        };
-
-        const reflectionResult = await this.reflectionManager.reflect(reflectionContext);
-
-        if (!reflectionResult.shouldRetry) {
-          throw lastError;
-        }
-
-        // Continue to next iteration for retry
-      }
-    }
-
-    throw lastError ?? new Error('Max reflection attempts exceeded');
-  }
-
-  /**
-   * Spawn a child workflow
-   */
-  async spawnWorkflow<T>(workflow: { run(): Promise<T>; id?: string; node?: WorkflowNode }): Promise<T> {
-    // If workflow has attachChild-like capability, use it
-    if ('node' in workflow && workflow.node) {
-      // Set parent reference
-      workflow.node.parent = this.workflow.node;
-
-      // Attach child node
-      this.workflow.node.children.push(workflow.node);
-
-      // Emit child attached event
-      this.workflow.emitEvent({
-        type: 'childAttached',
-        parentId: this.workflowId,
-        child: workflow.node,
-      });
-    }
-
-    // Run the child workflow
-    const result = await workflow.run();
-
-    // Rebuild event tree
-    this.eventTreeImpl.rebuild(this.workflow.node);
-
-    return result;
-  }
-
-  /**
-   * Replace the last prompt result with a new one (context revision)
-   * The previous prompt node is marked as 'revised' and the new result is attached as sibling
-   */
-  async replaceLastPromptResult<T>(
-    newPrompt: PromptLike<T>,
-    agent: AgentLike
-  ): Promise<T> {
-    // Find the last completed prompt node in the tree
-    const children = this.workflow.node.children;
-    let lastPromptNodeIndex = -1;
-
-    for (let i = children.length - 1; i >= 0; i--) {
-      const child = children[i];
-      if (child.status === 'completed') {
-        lastPromptNodeIndex = i;
-        break;
-      }
-    }
-
-    // Create a revision node to mark the replacement
-    const revisionNode: WorkflowNode = {
-      id: generateId(),
-      name: `revision:${newPrompt.id}`,
-      parent: this.workflow.node,
-      children: [],
-      status: 'running',
-      logs: [],
-      events: [],
-      stateSnapshot: null,
-    };
-
-    // If we found a previous node, mark it as revised
-    if (lastPromptNodeIndex >= 0) {
-      const previousNode = children[lastPromptNodeIndex];
-      // Mark as revised by adding a special status flag in logs
-      previousNode.logs.push({
-        id: generateId(),
-        workflowId: this.workflowId,
-        level: 'info',
-        message: `Revised by ${revisionNode.id}`,
-        timestamp: Date.now(),
-      });
-    }
-
-    // Attach revision node as sibling (at same level)
-    this.workflow.node.children.push(revisionNode);
-
-    // Emit prompt revision event
-    this.workflow.emitEvent({
-      type: 'stepStart',
-      node: revisionNode,
-      step: `revision:${newPrompt.id}`,
-    });
-
-    // Create execution context for this revision
-    const executionContext: AgentExecutionContext = {
-      workflowNode: revisionNode,
-      emitEvent: (event: WorkflowEvent) => {
-        revisionNode.events.push(event);
-        this.workflow.emitEvent(event);
-      },
-      workflowId: this.workflowId,
-      parentWorkflowId: this.parentWorkflowId,
-    };
-
-    try {
-      // Execute the new prompt in context
-      const result = await runInContext(executionContext, () =>
-        agent.prompt(newPrompt)
-      );
-
-      // Update revision node status
-      revisionNode.status = 'completed';
-
-      // Emit completion event
-      this.workflow.emitEvent({
-        type: 'stepEnd',
-        node: revisionNode,
-        step: `revision:${newPrompt.id}`,
-        duration: 0, // Could track actual duration if needed
-      });
-
-      // Rebuild event tree
-      this.eventTreeImpl.rebuild(this.workflow.node);
-
-      return result;
-    } catch (error) {
-      // Update revision node status
-      revisionNode.status = 'failed';
-
-      // Emit error event
-      this.workflow.emitEvent({
-        type: 'error',
-        node: revisionNode,
-        error: {
-          message: error instanceof Error ? error.message : 'Unknown error',
-          original: error,
-          workflowId: this.workflowId,
-          stack: error instanceof Error ? error.stack : undefined,
-          state: {},
-          logs: [],
-        },
-      });
-
-      // Rebuild event tree
-      this.eventTreeImpl.rebuild(this.workflow.node);
-
-      throw error;
-    }
-  }
-}
-
-/**
- * Create a WorkflowContext for a workflow
- * @param workflow The workflow object
- * @param parentWorkflowId Optional parent workflow ID
- * @param reflectionConfig Optional reflection configuration
- */
-export function createWorkflowContext(
-  workflow: WorkflowLike,
-  parentWorkflowId?: string,
-  reflectionConfig?: Partial<ReflectionConfig>
-): WorkflowContext {
-  return new WorkflowContextImpl(workflow, parentWorkflowId, reflectionConfig);
-}

package/src/core/workflow.ts

@@ -1,302 +0,0 @@
-import type {
-  WorkflowNode,
-  WorkflowStatus,
-  WorkflowEvent,
-  WorkflowObserver,
-} from '../types/index.js';
-import type { WorkflowContext, WorkflowConfig, WorkflowResult } from '../types/workflow-context.js';
-import { generateId } from '../utils/id.js';
-import { WorkflowLogger } from './logger.js';
-import { getObservedState } from '../decorators/observed-state.js';
-import { createWorkflowContext } from './workflow-context.js';
-
-/**
- * Executor function type for functional workflows
- */
-export type WorkflowExecutor<T = unknown> = (ctx: WorkflowContext) => Promise<T>;
-
-/**
- * Base class for all workflows
- * Supports both class-based (subclass with run()) and functional (executor) patterns
- *
- * @example Class-based pattern:
- * ```ts
- * class MyWorkflow extends Workflow {
- *   async run() {
- *     this.setStatus('running');
- *     // workflow logic
- *     this.setStatus('completed');
- *   }
- * }
- * ```
- *
- * @example Functional pattern:
- * ```ts
- * const workflow = new Workflow({ name: 'MyWorkflow' }, async (ctx) => {
- *   await ctx.step('step1', async () => {
- *     // step logic
- *   });
- * });
- * await workflow.run();
- * ```
- */
-export class Workflow<T = unknown> {
-  /** Unique identifier for this workflow instance */
-  public readonly id: string;
-
-  /** Parent workflow (null for root workflows) */
-  public parent: Workflow | null = null;
-
-  /** Child workflows */
-  public children: Workflow[] = [];
-
-  /** Current execution status */
-  public status: WorkflowStatus = 'idle';
-
-  /** Logger instance for this workflow */
-  protected readonly logger: WorkflowLogger;
-
-  /** The node representation of this workflow */
-  protected readonly node: WorkflowNode;
-
-  /** Observers (only populated on root workflow) */
-  private observers: WorkflowObserver[] = [];
-
-  /** Optional executor function for functional workflows */
-  private executor?: WorkflowExecutor<T>;
-
-  /** Workflow configuration */
-  private config: WorkflowConfig;
-
-  /**
-   * Create a new workflow instance
-   *
-   * @overload Class-based pattern
-   * @param name Human-readable name (defaults to class name)
-   * @param parent Optional parent workflow
-   *
-   * @overload Functional pattern
-   * @param config Workflow configuration
-   * @param executor Executor function
-   */
-  constructor(name?: string | WorkflowConfig, parentOrExecutor?: Workflow | WorkflowExecutor<T>) {
-    this.id = generateId();
-
-    // Parse overloaded arguments
-    if (typeof name === 'object' && name !== null) {
-      // Functional pattern: constructor(config, executor)
-      this.config = name;
-      this.executor = parentOrExecutor as WorkflowExecutor<T>;
-      this.parent = null;
-    } else {
-      // Class-based pattern: constructor(name, parent)
-      this.config = { name: name ?? this.constructor.name };
-      this.parent = (parentOrExecutor as Workflow) ?? null;
-    }
-
-    // Create the node representation
-    this.node = {
-      id: this.id,
-      name: this.config.name ?? this.constructor.name,
-      parent: this.parent?.node ?? null,
-      children: [],
-      status: 'idle',
-      logs: [],
-      events: [],
-      stateSnapshot: null,
-    };
-
-    // Create logger with root observers
-    this.logger = new WorkflowLogger(this.node, this.getRootObservers());
-
-    // Attach to parent if provided
-    if (this.parent) {
-      this.parent.attachChild(this);
-    }
-  }
-
-  /**
-   * Get observers from the root workflow
-   * Traverses up the tree to find the root
-   */
-  private getRootObservers(): WorkflowObserver[] {
-    if (this.parent) {
-      return this.parent.getRootObservers();
-    }
-    return this.observers;
-  }
-
-  /**
-   * Get the root workflow
-   */
-  protected getRoot(): Workflow {
-    if (this.parent) {
-      return this.parent.getRoot();
-    }
-    return this;
-  }
-
-  /**
-   * Add an observer to this workflow (must be root)
-   * @throws Error if called on non-root workflow
-   */
-  public addObserver(observer: WorkflowObserver): void {
-    if (this.parent) {
-      throw new Error('Observers can only be added to root workflows');
-    }
-    this.observers.push(observer);
-  }
-
-  /**
-   * Remove an observer from this workflow
-   */
-  public removeObserver(observer: WorkflowObserver): void {
-    const index = this.observers.indexOf(observer);
-    if (index !== -1) {
-      this.observers.splice(index, 1);
-    }
-  }
-
-  /**
-   * Attach a child workflow
-   * Called automatically in constructor when parent is provided
-   */
-  public attachChild(child: Workflow): void {
-    this.children.push(child);
-    this.node.children.push(child.node);
-
-    // Emit child attached event
-    this.emitEvent({
-      type: 'childAttached',
-      parentId: this.id,
-      child: child.node,
-    });
-  }
-
-  /**
-   * Emit an event to all root observers
-   */
-  public emitEvent(event: WorkflowEvent): void {
-    this.node.events.push(event);
-
-    const observers = this.getRootObservers();
-    for (const obs of observers) {
-      try {
-        obs.onEvent(event);
-
-        // Also notify tree changed for tree update events
-        if (event.type === 'treeUpdated' || event.type === 'childAttached') {
-          obs.onTreeChanged(this.getRoot().node);
-        }
-      } catch (err) {
-        console.error('Observer onEvent error:', err);
-      }
-    }
-  }
-
-  /**
-   * Capture and emit a state snapshot
-   */
-  public snapshotState(): void {
-    const snapshot = getObservedState(this);
-    this.node.stateSnapshot = snapshot;
-
-    // Notify observers
-    const observers = this.getRootObservers();
-    for (const obs of observers) {
-      try {
-        obs.onStateUpdated(this.node);
-      } catch (err) {
-        console.error('Observer onStateUpdated error:', err);
-      }
-    }
-
-    // Emit snapshot event
-    this.emitEvent({
-      type: 'stateSnapshot',
-      node: this.node,
-    });
-  }
-
-  /**
-   * Update workflow status and sync with node
-   */
-  public setStatus(status: WorkflowStatus): void {
-    this.status = status;
-    this.node.status = status;
-  }
-
-  /**
-   * Get the node representation of this workflow
-   */
-  public getNode(): WorkflowNode {
-    return this.node;
-  }
-
-  /**
-   * Run the workflow
-   *
-   * For functional workflows (created with executor), runs the executor function.
-   * For class-based workflows (subclasses), this should be overridden.
-   *
-   * @returns Workflow result
-   */
-  public async run(..._args: unknown[]): Promise<T | WorkflowResult<T>> {
-    if (this.executor) {
-      return this.runFunctional();
-    }
-
-    // Class-based workflows must override this method
-    throw new Error(
-      'Workflow.run() must be overridden in subclass or provide executor in constructor'
-    );
-  }
-
-  /**
-   * Run a functional workflow with context
-   */
-  private async runFunctional(): Promise<WorkflowResult<T>> {
-    if (!this.executor) {
-      throw new Error('No executor provided');
-    }
-
-    const startTime = Date.now();
-    this.setStatus('running');
-
-    // Create workflow context
-    const ctx = createWorkflowContext(
-      this as unknown as Parameters<typeof createWorkflowContext>[0],
-      this.parent?.id,
-      this.config.enableReflection ? { enabled: true } : undefined
-    );
-
-    try {
-      const result = await this.executor(ctx);
-      this.setStatus('completed');
-
-      return {
-        data: result,
-        node: this.node,
-        duration: Date.now() - startTime,
-      };
-    } catch (error) {
-      this.setStatus('failed');
-
-      // Emit error event
-      this.emitEvent({
-        type: 'error',
-        node: this.node,
-        error: {
-          message: error instanceof Error ? error.message : 'Unknown error',
-          original: error,
-          workflowId: this.id,
-          stack: error instanceof Error ? error.stack : undefined,
-          state: {},
-          logs: [],
-        },
-      });
-
-      throw error;
-    }
-  }
-}