groundswell 0.0.2 → 1.0.0

package/src/core/event-tree.ts

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

@@ -1,112 +0,0 @@
-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 directly to the node without notifying observers
-   * Used to avoid infinite recursion when observer.onLog() throws
-   */
-  private emitWithoutObserverNotification(entry: LogEntry): void {
-    this.node.logs.push(entry);
-  }
-
-  /**
-   * 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) {
-        // Create error entry and emit without observer notification to avoid infinite recursion
-        const errorEntry: LogEntry = {
-          id: generateId(),
-          workflowId: this.node.id,
-          timestamp: Date.now(),
-          level: 'error',
-          message: 'Observer onLog error',
-          data: { error: err },
-        };
-        this.emitWithoutObserverNotification(errorEntry);
-      }
-    }
-  }
-
-  /**
-   * 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
-   * @param parentLogId - ID of the parent log entry (legacy API)
-   */
-  child(parentLogId: string): WorkflowLogger;
-  /**
-   * Create a child logger with metadata
-   * @param meta - Partial log entry metadata (typically { parentLogId: string })
-   */
-  child(meta: Partial<LogEntry>): WorkflowLogger;
-  child(input: string | Partial<LogEntry>): WorkflowLogger {
-    const parentLogId = typeof input === 'string' ? input : input.parentLogId;
-    return new WorkflowLogger(this.node, this.observers, parentLogId);
-  }
-}

package/src/core/mcp-handler.ts

@@ -1,184 +0,0 @@
-/**
- * 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.`
-      );
-    };
-  }
-}

package/src/core/prompt.ts

@@ -1,150 +0,0 @@
-/**
- * Prompt<T> - Immutable type-safe prompt definition
- *
- * Prompts define what to send to an agent and how to validate the response.
- * They are value objects - immutable and reusable across agents and workflows.
- */
-
-import type { z } from 'zod';
-import type {
-  PromptConfig,
-  Tool,
-  MCPServer,
-  Skill,
-  AgentHooks,
-} from '../types/index.js';
-import { generateId } from '../utils/id.js';
-
-/**
- * Prompt class - immutable definition of a single agent call
- * @template T The expected response type (validated via Zod schema)
- */
-export class Prompt<T> {
-  /** Unique identifier for this prompt instance */
-  public readonly id: string;
-
-  /** User message content */
-  public readonly user: string;
-
-  /** Structured data to inject into the prompt */
-  public readonly data: Record<string, unknown>;
-
-  /** Zod schema defining the expected response format */
-  public readonly responseFormat: z.ZodType<T>;
-
-  /** System prompt override (takes precedence over agent config) */
-  public readonly systemOverride?: string;
-
-  /** Tools override */
-  public readonly toolsOverride?: Tool[];
-
-  /** MCPs override */
-  public readonly mcpsOverride?: MCPServer[];
-
-  /** Skills override */
-  public readonly skillsOverride?: Skill[];
-
-  /** Hooks override */
-  public readonly hooksOverride?: AgentHooks;
-
-  /** Enable reflection for this specific prompt */
-  public readonly enableReflection?: boolean;
-
-  /**
-   * Create a new Prompt instance
-   * @param config Prompt configuration
-   */
-  constructor(config: PromptConfig<T>) {
-    this.id = generateId();
-    this.user = config.user;
-    this.data = config.data ?? {};
-    this.responseFormat = config.responseFormat;
-    this.systemOverride = config.system;
-    this.toolsOverride = config.tools;
-    this.mcpsOverride = config.mcps;
-    this.skillsOverride = config.skills;
-    this.hooksOverride = config.hooks;
-    this.enableReflection = config.enableReflection;
-
-    // Freeze to ensure immutability
-    Object.freeze(this);
-    Object.freeze(this.data);
-  }
-
-  /**
-   * Validate a response against the response format schema
-   * @param data Unknown data to validate
-   * @returns Typed validated data
-   * @throws ZodError if validation fails
-   */
-  public validateResponse(data: unknown): T {
-    return this.responseFormat.parse(data);
-  }
-
-  /**
-   * Safely validate response without throwing
-   * @param data Unknown data to validate
-   * @returns Result object with success flag and data or error
-   */
-  public safeValidateResponse(
-    data: unknown
-  ): { success: true; data: T } | { success: false; error: z.ZodError } {
-    const result = this.responseFormat.safeParse(data);
-    if (result.success) {
-      return { success: true, data: result.data };
-    }
-    return { success: false, error: result.error };
-  }
-
-  /**
-   * Build the full user message including any injected data
-   * @returns Formatted user message
-   */
-  public buildUserMessage(): string {
-    if (Object.keys(this.data).length === 0) {
-      return this.user;
-    }
-
-    // Format data as a structured section
-    const dataSection = Object.entries(this.data)
-      .map(([key, value]) => `<${key}>\n${JSON.stringify(value, null, 2)}\n</${key}>`)
-      .join('\n\n');
-
-    return `${this.user}\n\n${dataSection}`;
-  }
-
-  /**
-   * Create a new Prompt with updated data (immutable pattern)
-   * @param newData Data to merge or replace
-   * @returns New Prompt instance
-   */
-  public withData(newData: Record<string, unknown>): Prompt<T> {
-    return new Prompt({
-      user: this.user,
-      data: { ...this.data, ...newData },
-      responseFormat: this.responseFormat,
-      system: this.systemOverride,
-      tools: this.toolsOverride,
-      mcps: this.mcpsOverride,
-      skills: this.skillsOverride,
-      hooks: this.hooksOverride,
-      enableReflection: this.enableReflection,
-    });
-  }
-
-  /**
-   * Get the prompt data (used for cache key generation)
-   * @returns The prompt data object
-   */
-  public getData(): Record<string, unknown> {
-    return this.data;
-  }
-
-  /**
-   * Get the response format schema (used for cache key generation)
-   * @returns The Zod response format schema
-   */
-  public getResponseFormat(): z.ZodType<T> {
-    return this.responseFormat;
-  }
-}