groundswell 0.0.2 → 1.0.0

package/src/types/index.ts

@@ -1,55 +0,0 @@
-// Core types
-export type { WorkflowStatus, WorkflowNode } from './workflow.js';
-export type { LogLevel, LogEntry } from './logging.js';
-export type { SerializedWorkflowState, StateFieldMetadata } from './snapshot.js';
-export type { WorkflowError } from './error.js';
-export type { WorkflowEvent } from './events.js';
-export type { WorkflowObserver } from './observer.js';
-export type { StepOptions, TaskOptions } from './decorators.js';
-export type { ErrorMergeStrategy } from './error-strategy.js';
-
-// SDK primitive types
-export type {
-  Tool,
-  ToolResult,
-  MCPServer,
-  Skill,
-  HookHandler,
-  PreToolUseContext,
-  PostToolUseContext,
-  SessionStartContext,
-  SessionEndContext,
-  AgentHooks,
-  TokenUsage,
-} from './sdk-primitives.js';
-
-// Agent types
-export type { AgentConfig, PromptOverrides } from './agent.js';
-
-// Prompt types
-export type { PromptConfig } from './prompt.js';
-
-// WorkflowContext types
-export type {
-  WorkflowContext,
-  WorkflowConfig,
-  WorkflowResult,
-  EventTreeHandle,
-  EventNode,
-  EventMetrics,
-  AgentLike,
-  PromptLike,
-} from './workflow-context.js';
-
-// Reflection types
-export type {
-  ReflectionAPI,
-  ReflectionConfig,
-  ReflectionContext,
-  ReflectionResult,
-  ReflectionEntry,
-} from './reflection.js';
-export {
-  DEFAULT_REFLECTION_CONFIG,
-  createReflectionConfig,
-} from './reflection.js';

package/src/types/logging.ts

@@ -1,24 +0,0 @@
-/**
- * Log severity levels
- */
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-
-/**
- * A single log entry in the workflow
- */
-export interface LogEntry {
-  /** Unique identifier for this log entry */
-  id: string;
-  /** ID of the workflow that created this log */
-  workflowId: string;
-  /** Unix timestamp in milliseconds */
-  timestamp: number;
-  /** Severity level */
-  level: LogLevel;
-  /** Log message */
-  message: string;
-  /** Optional structured data */
-  data?: unknown;
-  /** ID of parent log entry (for hierarchical logging) */
-  parentLogId?: string;
-}

package/src/types/observer.ts

@@ -1,18 +0,0 @@
-import type { LogEntry } from './logging.js';
-import type { WorkflowEvent } from './events.js';
-import type { WorkflowNode } from './workflow.js';
-
-/**
- * Observer interface for subscribing to workflow events
- * Observers attach to the root workflow and receive all events
- */
-export interface WorkflowObserver {
-  /** Called when a log entry is created */
-  onLog(entry: LogEntry): void;
-  /** Called when any workflow event occurs */
-  onEvent(event: WorkflowEvent): void;
-  /** Called when a node's state is updated */
-  onStateUpdated(node: WorkflowNode): void;
-  /** Called when the tree structure changes */
-  onTreeChanged(root: WorkflowNode): void;
-}

package/src/types/prompt.ts

@@ -1,40 +0,0 @@
-/**
- * Prompt configuration types
- * Prompts are immutable definitions of what to send to an agent
- */
-
-import type { z } from 'zod';
-import type { Tool, MCPServer, Skill, AgentHooks } from './sdk-primitives.js';
-
-/**
- * Configuration for creating a Prompt instance
- * @template T The expected response type (inferred from responseFormat)
- */
-export interface PromptConfig<T> {
-  /** User message content */
-  user: string;
-
-  /** Structured data to inject into the prompt */
-  data?: Record<string, unknown>;
-
-  /** Zod schema defining the expected response format */
-  responseFormat: z.ZodType<T>;
-
-  /** Override system prompt (takes precedence over agent config) */
-  system?: string;
-
-  /** Override tools (takes precedence over agent config) */
-  tools?: Tool[];
-
-  /** Override MCPs (takes precedence over agent config) */
-  mcps?: MCPServer[];
-
-  /** Override skills (takes precedence over agent config) */
-  skills?: Skill[];
-
-  /** Override hooks (takes precedence over agent config) */
-  hooks?: AgentHooks;
-
-  /** Enable reflection specifically for this prompt */
-  enableReflection?: boolean;
-}

package/src/types/reflection.ts

@@ -1,117 +0,0 @@
-/**
- * Reflection types - Interfaces for multi-level reflection and self-correction
- *
- * Reflection allows agents to analyze errors and retry with modified approaches.
- * Supports workflow, agent, and prompt level reflection with configurable limits.
- */
-
-import type { WorkflowNode } from './workflow.js';
-
-/**
- * Configuration for reflection behavior
- */
-export interface ReflectionConfig {
-  /** Whether reflection is enabled */
-  enabled: boolean;
-  /** Maximum number of reflection attempts (default: 3) */
-  maxAttempts: number;
-  /** Delay between retry attempts in milliseconds (default: 0) */
-  retryDelayMs?: number;
-}
-
-/**
- * Context provided to the reflection process
- */
-export interface ReflectionContext {
-  /** Level at which reflection is occurring */
-  level: 'workflow' | 'agent' | 'prompt';
-  /** The workflow node that failed */
-  failedNode: WorkflowNode;
-  /** The error that triggered reflection */
-  error: Error;
-  /** Current attempt number (1-indexed) */
-  attemptNumber: number;
-  /** History of previous reflection attempts */
-  previousAttempts: ReflectionEntry[];
-}
-
-/**
- * Result from a reflection analysis
- */
-export interface ReflectionResult {
-  /** Whether to retry the operation */
-  shouldRetry: boolean;
-  /** Revised prompt data for retry */
-  revisedPromptData?: Record<string, unknown>;
-  /** Revised system prompt for retry */
-  revisedSystemPrompt?: string;
-  /** Explanation of the reflection decision */
-  reason: string;
-}
-
-/**
- * Record of a single reflection attempt
- */
-export interface ReflectionEntry {
-  /** Timestamp when reflection occurred */
-  timestamp: number;
-  /** Level at which reflection occurred */
-  level: 'workflow' | 'agent' | 'prompt';
-  /** Reason for the reflection */
-  reason: string;
-  /** Original error that triggered reflection */
-  error: Error;
-  /** Resolution action taken */
-  resolution: 'retry' | 'skip' | 'abort';
-  /** Whether the retry was successful */
-  success: boolean;
-}
-
-/**
- * Full ReflectionAPI interface for workflow contexts
- */
-export interface ReflectionAPI {
-  /**
-   * Check if reflection is enabled
-   */
-  isEnabled(): boolean;
-
-  /**
-   * Trigger a reflection on the current context
-   * @param reason Optional reason for the reflection
-   */
-  triggerReflection(reason?: string): Promise<void>;
-
-  /**
-   * Get the history of reflection attempts
-   */
-  getReflectionHistory(): ReflectionEntry[];
-
-  /**
-   * Perform reflection analysis on an error
-   * @param context The reflection context with error details
-   * @returns Result indicating whether to retry
-   */
-  reflect(context: ReflectionContext): Promise<ReflectionResult>;
-}
-
-/**
- * Default reflection configuration
- */
-export const DEFAULT_REFLECTION_CONFIG: ReflectionConfig = {
-  enabled: false,
-  maxAttempts: 3,
-  retryDelayMs: 0,
-};
-
-/**
- * Create a reflection config with defaults
- */
-export function createReflectionConfig(
-  partial?: Partial<ReflectionConfig>
-): ReflectionConfig {
-  return {
-    ...DEFAULT_REFLECTION_CONFIG,
-    ...partial,
-  };
-}

package/src/types/sdk-primitives.ts

@@ -1,128 +0,0 @@
-/**
- * SDK primitive types that mirror Anthropic SDK structures
- * These types pass through unchanged to the SDK
- */
-
-/**
- * Tool definition for Anthropic SDK
- * Maps directly to Anthropic.Tool
- */
-export interface Tool {
-  /** Tool name (must be unique within an agent) */
-  name: string;
-  /** Human-readable description of what the tool does */
-  description: string;
-  /** JSON Schema describing the tool's input parameters */
-  input_schema: {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-}
-
-/**
- * Tool result returned from tool execution
- */
-export interface ToolResult {
-  type: 'tool_result';
-  tool_use_id: string;
-  content: string | unknown;
-  is_error?: boolean;
-}
-
-/**
- * MCP Server configuration
- * Supports stdio and inprocess transports
- */
-export interface MCPServer {
-  /** Server name for identification */
-  name: string;
-  /** Server version (optional) */
-  version?: string;
-  /** Transport type */
-  transport: 'stdio' | 'inprocess';
-  /** Command to run for stdio transport */
-  command?: string;
-  /** Arguments for the command */
-  args?: string[];
-  /** Tools provided by this MCP server */
-  tools?: Tool[];
-  /** Environment variables for the MCP process */
-  env?: Record<string, string>;
-}
-
-/**
- * Skill definition
- * Skills are loaded from directories containing SKILL.md
- */
-export interface Skill {
-  /** Skill name for identification */
-  name: string;
-  /** Path to skill directory containing SKILL.md */
-  path: string;
-}
-
-/**
- * Hook handler function type
- */
-export type HookHandler<T = unknown> = (context: T) => Promise<void> | void;
-
-/**
- * Pre-tool use hook context
- */
-export interface PreToolUseContext {
-  toolName: string;
-  toolInput: unknown;
-  agentId: string;
-}
-
-/**
- * Post-tool use hook context
- */
-export interface PostToolUseContext {
-  toolName: string;
-  toolInput: unknown;
-  toolOutput: unknown;
-  agentId: string;
-  duration: number;
-}
-
-/**
- * Session start hook context
- */
-export interface SessionStartContext {
-  agentId: string;
-  agentName?: string;
-}
-
-/**
- * Session end hook context
- */
-export interface SessionEndContext {
-  agentId: string;
-  agentName?: string;
-  totalDuration: number;
-}
-
-/**
- * Agent lifecycle hooks
- * Maps to Anthropic SDK hook conventions
- */
-export interface AgentHooks {
-  /** Called before each tool invocation */
-  preToolUse?: HookHandler<PreToolUseContext>[];
-  /** Called after each tool invocation */
-  postToolUse?: HookHandler<PostToolUseContext>[];
-  /** Called when agent session starts */
-  sessionStart?: HookHandler<SessionStartContext>[];
-  /** Called when agent session ends */
-  sessionEnd?: HookHandler<SessionEndContext>[];
-}
-
-/**
- * Token usage information from API response
- */
-export interface TokenUsage {
-  input_tokens: number;
-  output_tokens: number;
-}

package/src/types/workflow-context.ts

@@ -1,163 +0,0 @@
-/**
- * WorkflowContext - Interface for functional workflow execution
- *
- * Provides step(), spawnWorkflow(), and other methods for
- * composing workflows in arbitrary JavaScript control flow.
- */
-
-import type { WorkflowNode } from './workflow.js';
-import type { ReflectionAPI } from './reflection.js';
-
-// Re-export ReflectionAPI for backward compatibility
-export type { ReflectionAPI } from './reflection.js';
-
-/**
- * Handle for querying the event tree
- */
-export interface EventTreeHandle {
-  /** Root node of the event tree */
-  readonly root: EventNode;
-
-  /**
-   * Get a node by ID
-   * @param id Node ID to find
-   */
-  getNode(id: string): EventNode | undefined;
-
-  /**
-   * Get all children of a node
-   * @param id Parent node ID
-   */
-  getChildren(id: string): EventNode[];
-
-  /**
-   * Get all ancestors of a node (from node up to root)
-   * @param id Node ID
-   */
-  getAncestors(id: string): EventNode[];
-
-  /**
-   * Export tree as JSON
-   */
-  toJSON(): EventNode;
-}
-
-/**
- * Event node in the queryable tree
- */
-export interface EventNode {
-  id: string;
-  type: string;
-  timestamp: number;
-  name?: string;
-  payload?: unknown;
-  metrics?: EventMetrics;
-  parentId?: string;
-  children: EventNode[];
-}
-
-/**
- * Metrics associated with an event node
- */
-export interface EventMetrics {
-  duration?: number;
-  tokenUsage?: {
-    input: number;
-    output: number;
-  };
-  toolCalls?: number;
-}
-
-/**
- * Agent interface for context revision (minimal to avoid circular deps)
- */
-export interface AgentLike {
-  prompt<T>(prompt: PromptLike<T>): Promise<T>;
-}
-
-/**
- * Prompt interface for context revision (minimal to avoid circular deps)
- */
-export interface PromptLike<T> {
-  id: string;
-  buildUserMessage(): string;
-  validateResponse(data: unknown): T;
-}
-
-/**
- * WorkflowContext - Available within functional workflow executor
- */
-export interface WorkflowContext {
-  /** Unique ID of this workflow */
-  readonly workflowId: string;
-
-  /** Parent workflow ID if nested */
-  readonly parentWorkflowId?: string;
-
-  /**
-   * Execute a named step
-   * Can be called anywhere in JavaScript control flow (loops, conditionals, etc.)
-   *
-   * @param name Step name for logging and debugging
-   * @param fn Step function to execute
-   * @returns Result of the step function
-   */
-  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
-
-  /**
-   * Spawn a child workflow
-   * The child workflow is automatically attached to this workflow's tree
-   *
-   * @param workflow Workflow instance to spawn
-   * @returns Result of the child workflow
-   */
-  spawnWorkflow<T>(workflow: { run(): Promise<T> }): Promise<T>;
-
-  /**
-   * 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
-   *
-   * @param newPrompt The new prompt to execute
-   * @param agent The agent to use for execution
-   * @returns Result of the new prompt
-   */
-  replaceLastPromptResult<T>(
-    newPrompt: PromptLike<T>,
-    agent: AgentLike
-  ): Promise<T>;
-
-  /**
-   * Access to the event tree for this workflow
-   */
-  readonly eventTree: EventTreeHandle;
-
-  /**
-   * Reflection API for error handling and retry logic
-   */
-  readonly reflection: ReflectionAPI;
-}
-
-/**
- * Configuration for creating a functional workflow
- */
-export interface WorkflowConfig {
-  /** Human-readable workflow name */
-  name?: string;
-
-  /** Enable reflection for this workflow */
-  enableReflection?: boolean;
-}
-
-/**
- * Result from workflow execution
- */
-export interface WorkflowResult<T = unknown> {
-  /** The result value */
-  data: T;
-
-  /** The workflow node */
-  node: WorkflowNode;
-
-  /** Total duration in milliseconds */
-  duration: number;
-}

package/src/types/workflow.ts

@@ -1,37 +0,0 @@
-/**
- * Workflow status representing the current execution state
- */
-export type WorkflowStatus =
-  | 'idle'
-  | 'running'
-  | 'completed'
-  | 'failed'
-  | 'cancelled';
-
-// Forward declarations - import from their respective files
-import type { LogEntry } from './logging.js';
-import type { WorkflowEvent } from './events.js';
-import type { SerializedWorkflowState } from './snapshot.js';
-
-/**
- * Represents a node in the workflow execution tree
- * This is the data structure, not the Workflow class
- */
-export interface WorkflowNode {
-  /** Unique identifier for this workflow instance */
-  id: string;
-  /** Human-readable name */
-  name: string;
-  /** Parent node reference (null for root) */
-  parent: WorkflowNode | null;
-  /** Child workflow nodes */
-  children: WorkflowNode[];
-  /** Current execution status */
-  status: WorkflowStatus;
-  /** Log entries for this node */
-  logs: LogEntry[];
-  /** Events emitted by this node */
-  events: WorkflowEvent[];
-  /** Optional serialized state snapshot */
-  stateSnapshot: SerializedWorkflowState | null;
-}

package/src/utils/id.ts

@@ -1,11 +0,0 @@
-/**
- * Generate a unique identifier
- * Uses crypto.randomUUID if available, falls back to timestamp + random
- */
-export function generateId(): string {
-  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-    return crypto.randomUUID();
-  }
-  // Fallback for environments without crypto.randomUUID
-  return `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 11)}`;
-}

package/src/utils/index.ts

@@ -1,4 +0,0 @@
-export { generateId } from './id.js';
-export { Observable } from './observable.js';
-export { mergeWorkflowErrors } from './workflow-error-utils.js';
-export type { Subscription, Observer } from './observable.js';

package/src/utils/observable.ts

@@ -1,106 +0,0 @@
-/**
- * Lightweight Observable implementation for event streaming
- * No external dependencies
- */
-export interface Subscription {
-  unsubscribe(): void;
-}
-
-export interface Observer<T> {
-  next?: (value: T) => void;
-  error?: (error: unknown) => void;
-  complete?: () => void;
-}
-
-/**
- * Logger interface for Observable error logging
- * Matches WorkflowLogger.error() signature for compatibility
- */
-export interface ObservableLogger {
-  error(message: string, data?: unknown): void;
-}
-
-export class Observable<T> {
-  private subscribers: Set<Observer<T>> = new Set();
-  private logger?: ObservableLogger;
-
-  /**
-   * Create a new Observable
-   * @param logger Optional logger for error reporting (falls back to console.error)
-   */
-  constructor(logger?: ObservableLogger) {
-    this.logger = logger;
-  }
-
-  /**
-   * Subscribe to this observable
-   * @returns Subscription with unsubscribe method
-   */
-  subscribe(observer: Observer<T>): Subscription {
-    this.subscribers.add(observer);
-    return {
-      unsubscribe: () => {
-        this.subscribers.delete(observer);
-      },
-    };
-  }
-
-  /**
-   * Log errors using injected logger or fallback to console.error
-   */
-  private logError(message: string, error: unknown): void {
-    if (this.logger) {
-      this.logger.error(message, { error });
-    } else {
-      // Fallback for backward compatibility
-      console.error(message, error);
-    }
-  }
-
-  /**
-   * Emit a value to all subscribers
-   */
-  next(value: T): void {
-    for (const subscriber of this.subscribers) {
-      try {
-        subscriber.next?.(value);
-      } catch (err) {
-        this.logError('Observable subscriber error', err);
-      }
-    }
-  }
-
-  /**
-   * Signal an error to all subscribers
-   */
-  error(err: unknown): void {
-    for (const subscriber of this.subscribers) {
-      try {
-        subscriber.error?.(err);
-      } catch (e) {
-        this.logError('Observable error handler failed', e);
-      }
-    }
-  }
-
-  /**
-   * Signal completion to all subscribers
-   */
-  complete(): void {
-    for (const subscriber of this.subscribers) {
-      try {
-        subscriber.complete?.();
-      } catch (err) {
-        this.logError('Observable complete handler failed', err);
-      }
-    }
-    this.subscribers.clear();
-  }
-
-  /**
-   * Get current subscriber count
-   */
-  get subscriberCount(): number {
-    return this.subscribers.size;
-  }
-}