groundswell 0.0.2 → 0.0.3

package/dist/core/mcp-handler.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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>;
+/**
+ * MCPHandler - Manages MCP server registration and tool execution
+ *
+ * Currently supports:
+ * - inprocess transport: Direct tool registration
+ * - stdio transport: Documented for future implementation
+ */
+export declare class MCPHandler {
+    /** Registered MCP servers */
+    private servers;
+    /** Registered tools from all servers */
+    private registeredTools;
+    /** Custom tool executors for inprocess servers */
+    private toolExecutors;
+    /**
+     * Register an MCP server
+     * @param server MCP server configuration
+     */
+    registerServer(server: MCPServer): void;
+    /**
+     * Unregister an MCP server
+     * @param name Server name to unregister
+     */
+    unregisterServer(name: string): void;
+    /**
+     * Register a custom tool executor for an inprocess tool
+     * @param serverName Server name
+     * @param toolName Tool name
+     * @param executor Executor function
+     */
+    registerToolExecutor(serverName: string, toolName: string, executor: ToolExecutor): void;
+    /**
+     * Get all tools from registered servers in Anthropic format
+     * @returns Array of Tool definitions
+     */
+    getTools(): Tool[];
+    /**
+     * Execute a tool by name
+     * @param toolName Full tool name (serverName__toolName)
+     * @param input Tool input
+     * @returns Tool result
+     */
+    executeTool(toolName: string, input: unknown): Promise<ToolResult>;
+    /**
+     * Check if a tool is registered
+     * @param toolName Tool name to check
+     */
+    hasTool(toolName: string): boolean;
+    /**
+     * Get registered server names
+     */
+    getServerNames(): string[];
+    /**
+     * Create a tool executor based on transport type
+     */
+    private createToolExecutor;
+}
+//# sourceMappingURL=mcp-handler.d.ts.map

package/dist/core/mcp-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-handler.d.ts","sourceRoot":"","sources":["../../src/core/mcp-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAWhE;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,6BAA6B;IAC7B,OAAO,CAAC,OAAO,CAAqC;IAEpD,wCAAwC;IACxC,OAAO,CAAC,eAAe,CAA0C;IAEjE,kDAAkD;IAClD,OAAO,CAAC,aAAa,CAAwC;IAE7D;;;OAGG;IACI,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAoB9C;;;OAGG;IACI,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAW3C;;;;;OAKG;IACI,oBAAoB,CACzB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,GACrB,IAAI;IAKP;;;OAGG;IACI,QAAQ,IAAI,IAAI,EAAE;IAIzB;;;;;OAKG;IACU,WAAW,CACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC;IA6BtB;;;OAGG;IACI,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIzC;;OAEG;IACI,cAAc,IAAI,MAAM,EAAE;IAIjC;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAyB3B"}

package/dist/core/mcp-handler.js

@@ -0,0 +1,143 @@
+/**
+ * MCP Handler - Manages MCP server connections and tool execution
+ *
+ * Provides integration with MCP (Model Context Protocol) servers,
+ * converting MCP tools to Anthropic Tool format.
+ */
+/**
+ * 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 */
+    servers = new Map();
+    /** Registered tools from all servers */
+    registeredTools = new Map();
+    /** Custom tool executors for inprocess servers */
+    toolExecutors = new Map();
+    /**
+     * Register an MCP server
+     * @param server MCP server configuration
+     */
+    registerServer(server) {
+        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
+     */
+    unregisterServer(name) {
+        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
+     */
+    registerToolExecutor(serverName, toolName, executor) {
+        const fullName = `${serverName}__${toolName}`;
+        this.toolExecutors.set(fullName, executor);
+    }
+    /**
+     * Get all tools from registered servers in Anthropic format
+     * @returns Array of Tool definitions
+     */
+    getTools() {
+        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
+     */
+    async executeTool(toolName, input) {
+        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
+     */
+    hasTool(toolName) {
+        return this.registeredTools.has(toolName);
+    }
+    /**
+     * Get registered server names
+     */
+    getServerNames() {
+        return Array.from(this.servers.keys());
+    }
+    /**
+     * Create a tool executor based on transport type
+     */
+    createToolExecutor(server, tool) {
+        const fullName = `${server.name}__${tool.name}`;
+        if (server.transport === 'inprocess') {
+            // For inprocess, look for registered executor
+            return async (input) => {
+                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) => {
+            throw new Error(`stdio transport for MCP server '${server.name}' is not yet implemented. ` +
+                `Use inprocess transport or register a custom executor.`);
+        };
+    }
+}
+//# sourceMappingURL=mcp-handler.js.map

package/dist/core/mcp-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-handler.js","sourceRoot":"","sources":["../../src/core/mcp-handler.ts"],"names":[],"mappings":"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"}

package/dist/core/prompt.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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';
+/**
+ * Prompt class - immutable definition of a single agent call
+ * @template T The expected response type (validated via Zod schema)
+ */
+export declare class Prompt<T> {
+    /** Unique identifier for this prompt instance */
+    readonly id: string;
+    /** User message content */
+    readonly user: string;
+    /** Structured data to inject into the prompt */
+    readonly data: Record<string, unknown>;
+    /** Zod schema defining the expected response format */
+    readonly responseFormat: z.ZodType<T>;
+    /** System prompt override (takes precedence over agent config) */
+    readonly systemOverride?: string;
+    /** Tools override */
+    readonly toolsOverride?: Tool[];
+    /** MCPs override */
+    readonly mcpsOverride?: MCPServer[];
+    /** Skills override */
+    readonly skillsOverride?: Skill[];
+    /** Hooks override */
+    readonly hooksOverride?: AgentHooks;
+    /** Enable reflection for this specific prompt */
+    readonly enableReflection?: boolean;
+    /**
+     * Create a new Prompt instance
+     * @param config Prompt configuration
+     */
+    constructor(config: PromptConfig<T>);
+    /**
+     * Validate a response against the response format schema
+     * @param data Unknown data to validate
+     * @returns Typed validated data
+     * @throws ZodError if validation fails
+     */
+    validateResponse(data: unknown): T;
+    /**
+     * Safely validate response without throwing
+     * @param data Unknown data to validate
+     * @returns Result object with success flag and data or error
+     */
+    safeValidateResponse(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: z.ZodError;
+    };
+    /**
+     * Build the full user message including any injected data
+     * @returns Formatted user message
+     */
+    buildUserMessage(): string;
+    /**
+     * Create a new Prompt with updated data (immutable pattern)
+     * @param newData Data to merge or replace
+     * @returns New Prompt instance
+     */
+    withData(newData: Record<string, unknown>): Prompt<T>;
+    /**
+     * Get the prompt data (used for cache key generation)
+     * @returns The prompt data object
+     */
+    getData(): Record<string, unknown>;
+    /**
+     * Get the response format schema (used for cache key generation)
+     * @returns The Zod response format schema
+     */
+    getResponseFormat(): z.ZodType<T>;
+}
+//# sourceMappingURL=prompt.d.ts.map

package/dist/core/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/core/prompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EACV,YAAY,EACZ,IAAI,EACJ,SAAS,EACT,KAAK,EACL,UAAU,EACX,MAAM,mBAAmB,CAAC;AAG3B;;;GAGG;AACH,qBAAa,MAAM,CAAC,CAAC;IACnB,iDAAiD;IACjD,SAAgB,EAAE,EAAE,MAAM,CAAC;IAE3B,2BAA2B;IAC3B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,gDAAgD;IAChD,SAAgB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE9C,uDAAuD;IACvD,SAAgB,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAE7C,kEAAkE;IAClE,SAAgB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExC,qBAAqB;IACrB,SAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC;IAEvC,oBAAoB;IACpB,SAAgB,YAAY,CAAC,EAAE,SAAS,EAAE,CAAC;IAE3C,sBAAsB;IACtB,SAAgB,cAAc,CAAC,EAAE,KAAK,EAAE,CAAC;IAEzC,qBAAqB;IACrB,SAAgB,aAAa,CAAC,EAAE,UAAU,CAAC;IAE3C,iDAAiD;IACjD,SAAgB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3C;;;OAGG;gBACS,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAiBnC;;;;;OAKG;IACI,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC;IAIzC;;;;OAIG;IACI,oBAAoB,CACzB,IAAI,EAAE,OAAO,GACZ;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAA;KAAE;IAQrE;;;OAGG;IACI,gBAAgB,IAAI,MAAM;IAajC;;;;OAIG;IACI,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAc5D;;;OAGG;IACI,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIzC;;;OAGG;IACI,iBAAiB,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;CAGzC"}

package/dist/core/prompt.js

@@ -0,0 +1,120 @@
+/**
+ * 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 { 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 {
+    /** Unique identifier for this prompt instance */
+    id;
+    /** User message content */
+    user;
+    /** Structured data to inject into the prompt */
+    data;
+    /** Zod schema defining the expected response format */
+    responseFormat;
+    /** System prompt override (takes precedence over agent config) */
+    systemOverride;
+    /** Tools override */
+    toolsOverride;
+    /** MCPs override */
+    mcpsOverride;
+    /** Skills override */
+    skillsOverride;
+    /** Hooks override */
+    hooksOverride;
+    /** Enable reflection for this specific prompt */
+    enableReflection;
+    /**
+     * Create a new Prompt instance
+     * @param config Prompt configuration
+     */
+    constructor(config) {
+        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
+     */
+    validateResponse(data) {
+        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
+     */
+    safeValidateResponse(data) {
+        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
+     */
+    buildUserMessage() {
+        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
+     */
+    withData(newData) {
+        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
+     */
+    getData() {
+        return this.data;
+    }
+    /**
+     * Get the response format schema (used for cache key generation)
+     * @returns The Zod response format schema
+     */
+    getResponseFormat() {
+        return this.responseFormat;
+    }
+}
+//# sourceMappingURL=prompt.js.map

package/dist/core/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/core/prompt.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow-context.d.ts

@@ -0,0 +1,57 @@
+/**
+ * WorkflowContextImpl - Implementation of functional workflow context
+ *
+ * Provides step(), spawnWorkflow(), and automatic context propagation
+ * for agents and prompts executed within workflows.
+ */
+import type { WorkflowContext, EventTreeHandle, ReflectionAPI, AgentLike, PromptLike } from '../types/workflow-context.js';
+import type { WorkflowNode, WorkflowEvent, ReflectionConfig } from '../types/index.js';
+/**
+ * Interface for workflow-like objects that can emit events
+ */
+interface WorkflowLike {
+    id: string;
+    node: WorkflowNode;
+    emitEvent(event: WorkflowEvent): void;
+    setStatus(status: 'idle' | 'running' | 'completed' | 'failed' | 'cancelled'): void;
+    attachChild(child: WorkflowLike): void;
+}
+/**
+ * WorkflowContext implementation
+ */
+export declare class WorkflowContextImpl implements WorkflowContext {
+    readonly workflowId: string;
+    readonly parentWorkflowId?: string;
+    readonly eventTree: EventTreeHandle;
+    readonly reflection: ReflectionAPI;
+    private workflow;
+    private eventTreeImpl;
+    private reflectionManager;
+    constructor(workflow: WorkflowLike, parentWorkflowId?: string, reflectionConfig?: Partial<ReflectionConfig>);
+    /**
+     * Execute a named step with automatic context propagation and reflection support
+     */
+    step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Spawn a child workflow
+     */
+    spawnWorkflow<T>(workflow: {
+        run(): Promise<T>;
+        id?: string;
+        node?: WorkflowNode;
+    }): 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
+     */
+    replaceLastPromptResult<T>(newPrompt: PromptLike<T>, agent: AgentLike): Promise<T>;
+}
+/**
+ * Create a WorkflowContext for a workflow
+ * @param workflow The workflow object
+ * @param parentWorkflowId Optional parent workflow ID
+ * @param reflectionConfig Optional reflection configuration
+ */
+export declare function createWorkflowContext(workflow: WorkflowLike, parentWorkflowId?: string, reflectionConfig?: Partial<ReflectionConfig>): WorkflowContext;
+export {};
+//# sourceMappingURL=workflow-context.d.ts.map

package/dist/core/workflow-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-context.d.ts","sourceRoot":"","sources":["../../src/core/workflow-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,aAAa,EACb,SAAS,EACT,UAAU,EACX,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAGjB,MAAM,mBAAmB,CAAC;AAW3B;;GAEG;AACH,UAAU,YAAY;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,IAAI,CAAC;IACnF,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CACxC;AAED;;GAEG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1C,SAAgB,SAAS,EAAE,eAAe,CAAC;IAC3C,SAAgB,UAAU,EAAE,aAAa,CAAC;IAE1C,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,iBAAiB,CAAoB;gBAG3C,QAAQ,EAAE,YAAY,EACtB,gBAAgB,CAAC,EAAE,MAAM,EACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAiB9C;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAsH7D;;OAEG;IACG,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE;QAAE,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,YAAY,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IA0BrG;;;OAGG;IACG,uBAAuB,CAAC,CAAC,EAC7B,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,EACxB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,CAAC,CAAC;CAwGd;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EACtB,gBAAgB,CAAC,EAAE,MAAM,EACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAC3C,eAAe,CAEjB"}