groundswell 0.0.1

package/src/core/event-tree.ts

@@ -0,0 +1,260 @@
+/**
+ * EventTreeHandle - Queryable interface for the workflow event tree
+ *
+ * Provides methods for traversing and querying the event tree
+ * that mirrors workflow execution.
+ */
+
+import type {
+  EventTreeHandle,
+  EventNode,
+  EventMetrics,
+} from '../types/workflow-context.js';
+import type { WorkflowNode, WorkflowEvent } from '../types/index.js';
+
+/**
+ * Implementation of EventTreeHandle
+ */
+export class EventTreeHandleImpl implements EventTreeHandle {
+  /** Root node of the tree */
+  public readonly root: EventNode;
+
+  /** Index of nodes by ID for fast lookup */
+  private nodeIndex: Map<string, EventNode> = new Map();
+
+  /**
+   * Create a new EventTreeHandle from a workflow node
+   * @param workflowNode Root workflow node
+   */
+  constructor(workflowNode: WorkflowNode) {
+    this.root = this.buildEventNode(workflowNode);
+    this.buildIndex(this.root);
+  }
+
+  /**
+   * Get a node by ID
+   * @param id Node ID to find
+   */
+  public getNode(id: string): EventNode | undefined {
+    return this.nodeIndex.get(id);
+  }
+
+  /**
+   * Get all children of a node
+   * @param id Parent node ID
+   */
+  public getChildren(id: string): EventNode[] {
+    const node = this.nodeIndex.get(id);
+    return node?.children ?? [];
+  }
+
+  /**
+   * Get all ancestors of a node (from node up to root, excluding the node itself)
+   * @param id Node ID
+   */
+  public getAncestors(id: string): EventNode[] {
+    const ancestors: EventNode[] = [];
+    const node = this.nodeIndex.get(id);
+
+    if (!node || !node.parentId) {
+      return ancestors;
+    }
+
+    let currentId = node.parentId;
+    while (currentId) {
+      const parent = this.nodeIndex.get(currentId);
+      if (!parent) break;
+      ancestors.push(parent);
+      currentId = parent.parentId ?? '';
+    }
+
+    return ancestors;
+  }
+
+  /**
+   * Export tree as JSON
+   */
+  public toJSON(): EventNode {
+    return this.cloneNode(this.root);
+  }
+
+  /**
+   * Rebuild the tree from an updated workflow node
+   * @param workflowNode Updated workflow node
+   */
+  public rebuild(workflowNode: WorkflowNode): void {
+    const newRoot = this.buildEventNode(workflowNode);
+    (this.root as { children: EventNode[] }).children = newRoot.children;
+    Object.assign(this.root, {
+      type: newRoot.type,
+      name: newRoot.name,
+      timestamp: newRoot.timestamp,
+      metrics: newRoot.metrics,
+    });
+
+    this.nodeIndex.clear();
+    this.buildIndex(this.root);
+  }
+
+  /**
+   * Build an EventNode from a WorkflowNode
+   */
+  private buildEventNode(
+    wfNode: WorkflowNode,
+    parentId?: string
+  ): EventNode {
+    const eventNode: EventNode = {
+      id: wfNode.id,
+      type: 'workflow',
+      timestamp: Date.now(),
+      name: wfNode.name,
+      parentId,
+      children: [],
+      metrics: this.extractMetrics(wfNode),
+    };
+
+    // Add event nodes from workflow events
+    for (const event of wfNode.events) {
+      const childNode = this.eventToNode(event, wfNode.id);
+      if (childNode) {
+        eventNode.children.push(childNode);
+      }
+    }
+
+    // Add child workflow nodes
+    for (const child of wfNode.children) {
+      eventNode.children.push(this.buildEventNode(child, wfNode.id));
+    }
+
+    return eventNode;
+  }
+
+  /**
+   * Convert a WorkflowEvent to an EventNode
+   */
+  private eventToNode(
+    event: WorkflowEvent,
+    parentId: string
+  ): EventNode | null {
+    const baseNode: Omit<EventNode, 'type' | 'payload'> = {
+      id: `${parentId}-${event.type}-${Date.now()}`,
+      timestamp: Date.now(),
+      parentId,
+      children: [],
+    };
+
+    switch (event.type) {
+      case 'stepStart':
+        return {
+          ...baseNode,
+          type: 'step',
+          name: event.step,
+        };
+
+      case 'stepEnd':
+        return {
+          ...baseNode,
+          type: 'stepComplete',
+          name: event.step,
+          metrics: { duration: event.duration },
+        };
+
+      case 'agentPromptStart':
+        return {
+          ...baseNode,
+          id: `${event.agentId}-prompt-${event.promptId}`,
+          type: 'agentPrompt',
+          name: event.agentName,
+          payload: { promptId: event.promptId },
+        };
+
+      case 'agentPromptEnd':
+        return {
+          ...baseNode,
+          id: `${event.agentId}-promptEnd-${event.promptId}`,
+          type: 'agentPromptComplete',
+          name: event.agentName,
+          metrics: {
+            duration: event.duration,
+            tokenUsage: event.tokenUsage
+              ? {
+                  input: event.tokenUsage.input_tokens,
+                  output: event.tokenUsage.output_tokens,
+                }
+              : undefined,
+          },
+        };
+
+      case 'toolInvocation':
+        return {
+          ...baseNode,
+          type: 'tool',
+          name: event.toolName,
+          payload: { input: event.input, output: event.output },
+          metrics: { duration: event.duration },
+        };
+
+      case 'error':
+        return {
+          ...baseNode,
+          type: 'error',
+          name: event.error.message,
+          payload: event.error,
+        };
+
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Extract metrics from a workflow node
+   */
+  private extractMetrics(wfNode: WorkflowNode): EventMetrics | undefined {
+    // Calculate total duration from step events
+    const stepEndEvents = wfNode.events.filter(
+      (e) => e.type === 'stepEnd'
+    ) as Array<{ type: 'stepEnd'; duration: number }>;
+
+    if (stepEndEvents.length === 0) {
+      return undefined;
+    }
+
+    const totalDuration = stepEndEvents.reduce(
+      (sum, e) => sum + e.duration,
+      0
+    );
+
+    return { duration: totalDuration };
+  }
+
+  /**
+   * Build index of all nodes
+   */
+  private buildIndex(node: EventNode): void {
+    this.nodeIndex.set(node.id, node);
+    for (const child of node.children) {
+      this.buildIndex(child);
+    }
+  }
+
+  /**
+   * Deep clone a node for JSON export
+   */
+  private cloneNode(node: EventNode): EventNode {
+    return {
+      ...node,
+      children: node.children.map((c) => this.cloneNode(c)),
+    };
+  }
+}
+
+/**
+ * Create an EventTreeHandle from a workflow node
+ * @param workflowNode Root workflow node
+ */
+export function createEventTreeHandle(
+  workflowNode: WorkflowNode
+): EventTreeHandle {
+  return new EventTreeHandleImpl(workflowNode);
+}

package/src/core/factory.ts

@@ -0,0 +1,123 @@
+/**
+ * Factory Functions - Convenience functions for dynamic workflow, agent, and prompt creation
+ *
+ * These functions provide a simple API for creating workflow components dynamically
+ * at runtime, useful for metaprogramming and agent-driven workflow construction.
+ */
+
+import { Workflow, type WorkflowExecutor } from './workflow.js';
+import { Agent } from './agent.js';
+import { Prompt } from './prompt.js';
+import type { WorkflowConfig } from '../types/workflow-context.js';
+import type { AgentConfig, PromptConfig } from '../types/index.js';
+
+/**
+ * Create a new Workflow instance
+ *
+ * @param config Workflow configuration
+ * @param executor Executor function that receives WorkflowContext
+ * @returns Configured Workflow instance
+ *
+ * @example
+ * ```ts
+ * const workflow = createWorkflow(
+ *   { name: 'DataPipeline', enableReflection: true },
+ *   async (ctx) => {
+ *     const data = await ctx.step('fetch', () => fetchData());
+ *     const processed = await ctx.step('process', () => processData(data));
+ *     return processed;
+ *   }
+ * );
+ *
+ * const result = await workflow.run();
+ * ```
+ */
+export function createWorkflow<T>(
+  config: WorkflowConfig,
+  executor: WorkflowExecutor<T>
+): Workflow<T> {
+  return new Workflow(config, executor);
+}
+
+/**
+ * Create a new Agent instance
+ *
+ * @param config Agent configuration
+ * @returns Configured Agent instance
+ *
+ * @example
+ * ```ts
+ * const agent = createAgent({
+ *   name: 'DataAnalyst',
+ *   system: 'You analyze data and provide insights.',
+ *   enableCache: true,
+ *   enableReflection: true,
+ * });
+ *
+ * const result = await agent.prompt(analysisPrompt);
+ * ```
+ */
+export function createAgent(config: AgentConfig): Agent {
+  return new Agent(config);
+}
+
+/**
+ * Create a new Prompt instance
+ *
+ * @param config Prompt configuration
+ * @returns Configured Prompt instance
+ *
+ * @example
+ * ```ts
+ * const prompt = createPrompt({
+ *   user: 'Analyze this data',
+ *   data: { values: [1, 2, 3, 4, 5] },
+ *   responseFormat: z.object({
+ *     summary: z.string(),
+ *     insights: z.array(z.string()),
+ *   }),
+ * });
+ *
+ * const result = await agent.prompt(prompt);
+ * ```
+ */
+export function createPrompt<T>(config: PromptConfig<T>): Prompt<T> {
+  return new Prompt(config);
+}
+
+/**
+ * Create a workflow with an inline executor (shorthand)
+ *
+ * @param name Workflow name
+ * @param executor Executor function
+ * @returns Configured Workflow instance
+ *
+ * @example
+ * ```ts
+ * const workflow = quickWorkflow('ProcessData', async (ctx) => {
+ *   return await ctx.step('process', () => processData());
+ * });
+ * ```
+ */
+export function quickWorkflow<T>(
+  name: string,
+  executor: WorkflowExecutor<T>
+): Workflow<T> {
+  return new Workflow({ name }, executor);
+}
+
+/**
+ * Create a simple agent with minimal configuration (shorthand)
+ *
+ * @param name Agent name
+ * @param system System prompt
+ * @returns Configured Agent instance
+ *
+ * @example
+ * ```ts
+ * const agent = quickAgent('Helper', 'You are a helpful assistant.');
+ * ```
+ */
+export function quickAgent(name: string, system?: string): Agent {
+  return new Agent({ name, system });
+}

package/src/core/index.ts

@@ -0,0 +1,17 @@
+export { WorkflowLogger } from './logger.js';
+export { Workflow, type WorkflowExecutor } from './workflow.js';
+export { Agent, type PromptResult } from './agent.js';
+export { Prompt } from './prompt.js';
+export { MCPHandler, type ToolExecutor } from './mcp-handler.js';
+export { EventTreeHandleImpl, createEventTreeHandle } from './event-tree.js';
+export { WorkflowContextImpl, createWorkflowContext } from './workflow-context.js';
+export {
+  getExecutionContext,
+  requireExecutionContext,
+  runInContext,
+  runInContextSync,
+  hasExecutionContext,
+  createChildContext,
+  agentExecutionStorage,
+  type AgentExecutionContext,
+} from './context.js';

package/src/core/logger.ts

@@ -0,0 +1,87 @@
+import type { WorkflowNode, LogEntry, LogLevel, WorkflowObserver } from '../types/index.js';
+import { generateId } from '../utils/id.js';
+
+/**
+ * Logger that emits log entries to workflow node and observers
+ */
+export class WorkflowLogger {
+  private readonly parentLogId?: string;
+
+  constructor(
+    private readonly node: WorkflowNode,
+    private readonly observers: WorkflowObserver[],
+    parentLogId?: string
+  ) {
+    this.parentLogId = parentLogId;
+  }
+
+  /**
+   * Emit a log entry to the node and all observers
+   */
+  private emit(entry: LogEntry): void {
+    this.node.logs.push(entry);
+    for (const obs of this.observers) {
+      try {
+        obs.onLog(entry);
+      } catch (err) {
+        console.error('Observer onLog error:', err);
+      }
+    }
+  }
+
+  /**
+   * Create a log entry with the given level
+   */
+  private log(level: LogLevel, message: string, data?: unknown): void {
+    const entry: LogEntry = {
+      id: generateId(),
+      workflowId: this.node.id,
+      timestamp: Date.now(),
+      level,
+      message,
+      data,
+    };
+
+    // Add parent log ID if this is a child logger
+    if (this.parentLogId) {
+      entry.parentLogId = this.parentLogId;
+    }
+
+    this.emit(entry);
+  }
+
+  /**
+   * Log a debug message
+   */
+  debug(message: string, data?: unknown): void {
+    this.log('debug', message, data);
+  }
+
+  /**
+   * Log an info message
+   */
+  info(message: string, data?: unknown): void {
+    this.log('info', message, data);
+  }
+
+  /**
+   * Log a warning message
+   */
+  warn(message: string, data?: unknown): void {
+    this.log('warn', message, data);
+  }
+
+  /**
+   * Log an error message
+   */
+  error(message: string, data?: unknown): void {
+    this.log('error', message, data);
+  }
+
+  /**
+   * Create a child logger that includes parentLogId
+   */
+  child(parentLogId: string): WorkflowLogger {
+    return new WorkflowLogger(this.node, this.observers, parentLogId);
+  }
+}

package/src/core/mcp-handler.ts

@@ -0,0 +1,184 @@
+/**
+ * MCP Handler - Manages MCP server connections and tool execution
+ *
+ * Provides integration with MCP (Model Context Protocol) servers,
+ * converting MCP tools to Anthropic Tool format.
+ */
+
+import type { MCPServer, Tool, ToolResult } from '../types/index.js';
+
+/**
+ * Tool executor function type
+ */
+export type ToolExecutor = (input: unknown) => Promise<unknown>;
+
+/**
+ * Registered tool with its executor
+ */
+interface RegisteredTool {
+  tool: Tool;
+  executor: ToolExecutor;
+  serverName: string;
+}
+
+/**
+ * MCPHandler - Manages MCP server registration and tool execution
+ *
+ * Currently supports:
+ * - inprocess transport: Direct tool registration
+ * - stdio transport: Documented for future implementation
+ */
+export class MCPHandler {
+  /** Registered MCP servers */
+  private servers: Map<string, MCPServer> = new Map();
+
+  /** Registered tools from all servers */
+  private registeredTools: Map<string, RegisteredTool> = new Map();
+
+  /** Custom tool executors for inprocess servers */
+  private toolExecutors: Map<string, ToolExecutor> = new Map();
+
+  /**
+   * Register an MCP server
+   * @param server MCP server configuration
+   */
+  public registerServer(server: MCPServer): void {
+    if (this.servers.has(server.name)) {
+      throw new Error(`MCP server '${server.name}' is already registered`);
+    }
+
+    this.servers.set(server.name, server);
+
+    // Register tools from the server
+    if (server.tools) {
+      for (const tool of server.tools) {
+        const fullName = `${server.name}__${tool.name}`;
+        this.registeredTools.set(fullName, {
+          tool: { ...tool, name: fullName },
+          executor: this.createToolExecutor(server, tool),
+          serverName: server.name,
+        });
+      }
+    }
+  }
+
+  /**
+   * Unregister an MCP server
+   * @param name Server name to unregister
+   */
+  public unregisterServer(name: string): void {
+    const server = this.servers.get(name);
+    if (server?.tools) {
+      for (const tool of server.tools) {
+        const fullName = `${name}__${tool.name}`;
+        this.registeredTools.delete(fullName);
+      }
+    }
+    this.servers.delete(name);
+  }
+
+  /**
+   * Register a custom tool executor for an inprocess tool
+   * @param serverName Server name
+   * @param toolName Tool name
+   * @param executor Executor function
+   */
+  public registerToolExecutor(
+    serverName: string,
+    toolName: string,
+    executor: ToolExecutor
+  ): void {
+    const fullName = `${serverName}__${toolName}`;
+    this.toolExecutors.set(fullName, executor);
+  }
+
+  /**
+   * Get all tools from registered servers in Anthropic format
+   * @returns Array of Tool definitions
+   */
+  public getTools(): Tool[] {
+    return Array.from(this.registeredTools.values()).map((rt) => rt.tool);
+  }
+
+  /**
+   * Execute a tool by name
+   * @param toolName Full tool name (serverName__toolName)
+   * @param input Tool input
+   * @returns Tool result
+   */
+  public async executeTool(
+    toolName: string,
+    input: unknown
+  ): Promise<ToolResult> {
+    const registered = this.registeredTools.get(toolName);
+    if (!registered) {
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: `Tool '${toolName}' not found`,
+        is_error: true,
+      };
+    }
+
+    try {
+      const result = await registered.executor(input);
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: typeof result === 'string' ? result : JSON.stringify(result),
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: `Tool execution failed: ${message}`,
+        is_error: true,
+      };
+    }
+  }
+
+  /**
+   * Check if a tool is registered
+   * @param toolName Tool name to check
+   */
+  public hasTool(toolName: string): boolean {
+    return this.registeredTools.has(toolName);
+  }
+
+  /**
+   * Get registered server names
+   */
+  public getServerNames(): string[] {
+    return Array.from(this.servers.keys());
+  }
+
+  /**
+   * Create a tool executor based on transport type
+   */
+  private createToolExecutor(server: MCPServer, tool: Tool): ToolExecutor {
+    const fullName = `${server.name}__${tool.name}`;
+
+    if (server.transport === 'inprocess') {
+      // For inprocess, look for registered executor
+      return async (input: unknown) => {
+        const executor = this.toolExecutors.get(fullName);
+        if (!executor) {
+          throw new Error(
+            `No executor registered for inprocess tool '${fullName}'. ` +
+              `Use registerToolExecutor() to provide an executor.`
+          );
+        }
+        return executor(input);
+      };
+    }
+
+    // stdio transport - placeholder for future implementation
+    return async (_input: unknown) => {
+      throw new Error(
+        `stdio transport for MCP server '${server.name}' is not yet implemented. ` +
+          `Use inprocess transport or register a custom executor.`
+      );
+    };
+  }
+}