groundswell 0.0.1

package/src/types/index.ts

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

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

@@ -0,0 +1,18 @@
+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

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

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

@@ -0,0 +1,128 @@
+/**
+ * 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/snapshot.ts

@@ -0,0 +1,14 @@
+/**
+ * Serialized workflow state as key-value pairs
+ */
+export type SerializedWorkflowState = Record<string, unknown>;
+
+/**
+ * Metadata for observed state fields
+ */
+export interface StateFieldMetadata {
+  /** If true, field is not included in snapshots */
+  hidden?: boolean;
+  /** If true, value is shown as '***' in snapshots */
+  redact?: boolean;
+}

package/src/types/workflow-context.ts

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

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

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

@@ -0,0 +1,3 @@
+export { generateId } from './id.js';
+export { Observable } from './observable.js';
+export type { Subscription, Observer } from './observable.js';

package/src/utils/observable.ts

@@ -0,0 +1,77 @@
+/**
+ * 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;
+}
+
+export class Observable<T> {
+  private subscribers: Set<Observer<T>> = new Set();
+
+  /**
+   * Subscribe to this observable
+   * @returns Subscription with unsubscribe method
+   */
+  subscribe(observer: Observer<T>): Subscription {
+    this.subscribers.add(observer);
+    return {
+      unsubscribe: () => {
+        this.subscribers.delete(observer);
+      },
+    };
+  }
+
+  /**
+   * Emit a value to all subscribers
+   */
+  next(value: T): void {
+    for (const subscriber of this.subscribers) {
+      try {
+        subscriber.next?.(value);
+      } catch (err) {
+        console.error('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) {
+        console.error('Observable error handler failed:', e);
+      }
+    }
+  }
+
+  /**
+   * Signal completion to all subscribers
+   */
+  complete(): void {
+    for (const subscriber of this.subscribers) {
+      try {
+        subscriber.complete?.();
+      } catch (err) {
+        console.error('Observable complete handler failed:', err);
+      }
+    }
+    this.subscribers.clear();
+  }
+
+  /**
+   * Get current subscriber count
+   */
+  get subscriberCount(): number {
+    return this.subscribers.size;
+  }
+}