groundswell 0.0.1 → 0.0.3

package/src/index.ts

@@ -1,140 +0,0 @@
-// 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/reflection.ts

@@ -1,407 +0,0 @@
-/**
- * ReflectionManager - Implements reflection and self-correction for agents
- *
- * Provides multi-level reflection (workflow, agent, prompt) with configurable
- * retry limits and history tracking.
- */
-
-import type {
-  ReflectionAPI,
-  ReflectionConfig,
-  ReflectionContext,
-  ReflectionResult,
-  ReflectionEntry,
-  WorkflowEvent,
-} from '../types/index.js';
-import type { Agent } from '../core/agent.js';
-import type { Prompt } from '../core/prompt.js';
-import { z } from 'zod';
-
-/**
- * Schema for parsing reflection responses from the agent
- */
-const ReflectionResponseSchema = z.object({
-  shouldRetry: z.boolean(),
-  reason: z.string(),
-  revisedPromptData: z.record(z.unknown()).optional(),
-  revisedSystemPrompt: z.string().optional(),
-});
-
-/**
- * Default reflection prompt template
- */
-const REFLECTION_PROMPT_TEMPLATE = `A previous operation failed with the following error:
-
-Error: {{errorMessage}}
-Stack: {{errorStack}}
-
-Level: {{level}}
-Node: {{nodeName}} ({{nodeId}})
-Attempt: {{attemptNumber}} of {{maxAttempts}}
-
-Previous attempts:
-{{previousAttempts}}
-
-Analyze the error and determine:
-1. Can this operation be retried with modifications?
-2. What changes would help it succeed?
-3. Is this a transient error (worth retrying) or a fundamental issue (should abort)?
-
-Consider:
-- Rate limits and quota errors should NOT be retried via reflection
-- Authentication errors should NOT be retried via reflection
-- Schema validation errors may be retried with revised data
-- Logic errors may be retried with revised prompts
-
-Respond with JSON:
-{
-  "shouldRetry": boolean,
-  "reason": string,
-  "revisedPromptData": { /* optional revised data */ },
-  "revisedSystemPrompt": "optional revised system prompt"
-}`;
-
-/**
- * ReflectionManager - Manages reflection and self-correction
- */
-export class ReflectionManager implements ReflectionAPI {
-  private readonly config: ReflectionConfig;
-  private readonly history: ReflectionEntry[] = [];
-  private readonly agent?: Agent;
-  private eventEmitter?: (event: WorkflowEvent) => void;
-
-  /**
-   * Create a new ReflectionManager
-   * @param config Reflection configuration
-   * @param agent Optional agent to use for reflection analysis
-   */
-  constructor(config: ReflectionConfig, agent?: Agent) {
-    this.config = config;
-    this.agent = agent;
-  }
-
-  /**
-   * Set the event emitter for workflow events
-   */
-  setEventEmitter(emitter: (event: WorkflowEvent) => void): void {
-    this.eventEmitter = emitter;
-  }
-
-  /**
-   * Check if reflection is enabled
-   */
-  isEnabled(): boolean {
-    return this.config.enabled;
-  }
-
-  /**
-   * Get the maximum number of attempts
-   */
-  getMaxAttempts(): number {
-    return this.config.maxAttempts;
-  }
-
-  /**
-   * Get the retry delay in milliseconds
-   */
-  getRetryDelayMs(): number {
-    return this.config.retryDelayMs ?? 0;
-  }
-
-  /**
-   * Trigger a reflection on the current context
-   */
-  async triggerReflection(reason?: string): Promise<void> {
-    if (!this.config.enabled) {
-      throw new Error('Reflection is not enabled');
-    }
-
-    // Record that reflection was triggered
-    const entry: ReflectionEntry = {
-      timestamp: Date.now(),
-      level: 'workflow',
-      reason: reason ?? 'Manual reflection trigger',
-      error: new Error(reason ?? 'Manual trigger'),
-      resolution: 'skip',
-      success: false,
-    };
-
-    this.history.push(entry);
-  }
-
-  /**
-   * Get the history of reflection attempts
-   */
-  getReflectionHistory(): ReflectionEntry[] {
-    return [...this.history];
-  }
-
-  /**
-   * Perform reflection analysis on an error
-   */
-  async reflect(context: ReflectionContext): Promise<ReflectionResult> {
-    // Emit reflection start event
-    if (this.eventEmitter) {
-      this.eventEmitter({
-        type: 'reflectionStart',
-        level: context.level,
-        node: context.failedNode,
-      });
-    }
-
-    let result: ReflectionResult;
-
-    try {
-      // Check for non-retryable errors
-      if (this.isNonRetryableError(context.error)) {
-        result = {
-          shouldRetry: false,
-          reason: `Non-retryable error: ${context.error.message}`,
-        };
-      } else if (this.agent) {
-        // Use agent for reflection analysis
-        result = await this.reflectWithAgent(context);
-      } else {
-        // Use simple heuristic-based reflection
-        result = this.reflectWithHeuristics(context);
-      }
-
-      // Record the reflection entry
-      const entry: ReflectionEntry = {
-        timestamp: Date.now(),
-        level: context.level,
-        reason: result.reason,
-        error: context.error,
-        resolution: result.shouldRetry ? 'retry' : 'abort',
-        success: false, // Will be updated by caller if retry succeeds
-      };
-
-      this.history.push(entry);
-
-      // Apply retry delay if configured
-      if (result.shouldRetry && this.config.retryDelayMs) {
-        await this.delay(this.config.retryDelayMs);
-      }
-
-      return result;
-    } finally {
-      // Emit reflection end event
-      if (this.eventEmitter) {
-        this.eventEmitter({
-          type: 'reflectionEnd',
-          level: context.level,
-          success: result!?.shouldRetry ?? false,
-          node: context.failedNode,
-        });
-      }
-    }
-  }
-
-  /**
-   * Mark the last reflection entry as successful
-   */
-  markLastReflectionSuccessful(): void {
-    if (this.history.length > 0) {
-      this.history[this.history.length - 1].success = true;
-    }
-  }
-
-  /**
-   * Check if an error is non-retryable
-   */
-  private isNonRetryableError(error: Error): boolean {
-    const message = error.message.toLowerCase();
-
-    // Rate limit and quota errors
-    if (
-      message.includes('rate limit') ||
-      message.includes('quota exceeded') ||
-      message.includes('429')
-    ) {
-      return true;
-    }
-
-    // Authentication errors
-    if (
-      message.includes('authentication') ||
-      message.includes('unauthorized') ||
-      message.includes('401') ||
-      message.includes('403') ||
-      message.includes('invalid api key')
-    ) {
-      return true;
-    }
-
-    // Network errors that should use exponential backoff instead
-    if (
-      message.includes('econnrefused') ||
-      message.includes('etimedout') ||
-      message.includes('network')
-    ) {
-      return true;
-    }
-
-    return false;
-  }
-
-  /**
-   * Perform reflection using an agent
-   */
-  private async reflectWithAgent(
-    context: ReflectionContext
-  ): Promise<ReflectionResult> {
-    if (!this.agent) {
-      throw new Error('No agent configured for reflection');
-    }
-
-    // Build the reflection prompt
-    const promptText = this.buildReflectionPrompt(context);
-
-    // Create a prompt for reflection analysis
-    const reflectionPrompt = new (await import('../core/prompt.js')).Prompt({
-      user: promptText,
-      responseFormat: ReflectionResponseSchema,
-    });
-
-    try {
-      const response = await this.agent.prompt(reflectionPrompt);
-      return {
-        shouldRetry: response.shouldRetry,
-        reason: response.reason,
-        revisedPromptData: response.revisedPromptData,
-        revisedSystemPrompt: response.revisedSystemPrompt,
-      };
-    } catch (reflectionError) {
-      // If reflection itself fails, don't retry the original
-      return {
-        shouldRetry: false,
-        reason: `Reflection analysis failed: ${reflectionError instanceof Error ? reflectionError.message : 'Unknown error'}`,
-      };
-    }
-  }
-
-  /**
-   * Perform reflection using simple heuristics
-   */
-  private reflectWithHeuristics(context: ReflectionContext): ReflectionResult {
-    const errorMessage = context.error.message.toLowerCase();
-
-    // Check for validation errors (often retryable)
-    if (
-      errorMessage.includes('validation') ||
-      errorMessage.includes('parse') ||
-      errorMessage.includes('schema') ||
-      errorMessage.includes('json')
-    ) {
-      return {
-        shouldRetry: true,
-        reason:
-          'Validation/parsing error detected - retry may succeed with adjusted approach',
-      };
-    }
-
-    // Check for timeout errors
-    if (errorMessage.includes('timeout')) {
-      return {
-        shouldRetry: context.attemptNumber < 2,
-        reason:
-          context.attemptNumber < 2
-            ? 'Timeout error - retry once'
-            : 'Timeout error - too many attempts',
-      };
-    }
-
-    // Default: retry if under max attempts
-    const shouldRetry = context.attemptNumber < this.config.maxAttempts;
-    return {
-      shouldRetry,
-      reason: shouldRetry
-        ? `Attempt ${context.attemptNumber} failed - retrying`
-        : `Max attempts (${this.config.maxAttempts}) reached`,
-    };
-  }
-
-  /**
-   * Build the reflection prompt from context
-   */
-  private buildReflectionPrompt(context: ReflectionContext): string {
-    const previousAttemptsText =
-      context.previousAttempts.length > 0
-        ? context.previousAttempts
-            .map(
-              (a, i) =>
-                `  ${i + 1}. [${a.level}] ${a.reason} -> ${a.resolution} (${a.success ? 'success' : 'failed'})`
-            )
-            .join('\n')
-        : '  None';
-
-    return REFLECTION_PROMPT_TEMPLATE.replace('{{errorMessage}}', context.error.message)
-      .replace('{{errorStack}}', context.error.stack ?? 'No stack trace')
-      .replace('{{level}}', context.level)
-      .replace('{{nodeName}}', context.failedNode.name)
-      .replace('{{nodeId}}', context.failedNode.id)
-      .replace('{{attemptNumber}}', String(context.attemptNumber))
-      .replace('{{maxAttempts}}', String(this.config.maxAttempts))
-      .replace('{{previousAttempts}}', previousAttemptsText);
-  }
-
-  /**
-   * Helper to create a delay
-   */
-  private delay(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-}
-
-/**
- * Execute a function with reflection support
- * @param fn Function to execute
- * @param reflection ReflectionManager instance
- * @param createContext Function to create reflection context from error
- * @returns Result of the function
- */
-export async function executeWithReflection<T>(
-  fn: () => Promise<T>,
-  reflection: ReflectionManager,
-  createContext: (
-    error: Error,
-    attempt: number,
-    history: ReflectionEntry[]
-  ) => ReflectionContext
-): Promise<T> {
-  let lastError: Error | null = null;
-  const maxAttempts = reflection.getMaxAttempts();
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      const result = await fn();
-
-      // If we succeeded after a reflection, mark it as successful
-      if (attempt > 1) {
-        reflection.markLastReflectionSuccessful();
-      }
-
-      return result;
-    } catch (error) {
-      lastError = error as Error;
-
-      if (!reflection.isEnabled() || attempt === maxAttempts) {
-        throw error;
-      }
-
-      const context = createContext(
-        lastError,
-        attempt,
-        reflection.getReflectionHistory()
-      );
-
-      const result = await reflection.reflect(context);
-
-      if (!result.shouldRetry) {
-        throw lastError;
-      }
-    }
-  }
-
-  throw lastError ?? new Error('Max reflection attempts exceeded');
-}

package/src/tools/index.ts

@@ -1,36 +0,0 @@
-/**
- * Tools module exports
- */
-
-export {
-  // Tool definitions
-  INTROSPECTION_TOOLS,
-  inspectCurrentNodeTool,
-  readAncestorChainTool,
-  listSiblingsChildrenTool,
-  inspectPriorOutputsTool,
-  inspectCacheStatusTool,
-  requestSpawnWorkflowTool,
-  // Handlers
-  INTROSPECTION_HANDLERS,
-  handleInspectCurrentNode,
-  handleReadAncestorChain,
-  handleListSiblingsChildren,
-  handleInspectPriorOutputs,
-  handleInspectCacheStatus,
-  handleRequestSpawnWorkflow,
-  // Utilities
-  registerIntrospectionTools,
-  executeIntrospectionTool,
-} from './introspection.js';
-
-export type {
-  CurrentNodeInfo,
-  AncestorInfo,
-  AncestorChainResult,
-  NodeInfo,
-  SiblingsChildrenResult,
-  PriorOutputInfo,
-  CacheStatusResult,
-  SpawnWorkflowRequest,
-} from './introspection.js';