groundswell 0.0.2 → 1.0.0

package/dist/cache/cache.js.map

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

package/{src/cache/index.ts → dist/cache/index.d.ts}

@@ -1,8 +1,8 @@
 /**
  * Cache module exports
  */
-
 export { LLMCache, defaultCache } from './cache.js';
 export type { CacheConfig, CacheMetrics } from './cache.js';
 export { generateCacheKey, deterministicStringify, getSchemaHash } from './cache-key.js';
 export type { CacheKeyInputs } from './cache-key.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzF,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,6 @@
+/**
+ * Cache module exports
+ */
+export { LLMCache, defaultCache } from './cache.js';
+export { generateCacheKey, deterministicStringify, getSchemaHash } from './cache-key.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/core/agent.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Agent - Multi-provider agent for LLM prompt execution
+ *
+ * Agents execute prompts via provider abstraction layer, supporting
+ * multiple LLM providers (Anthropic, Claude Code, etc.) with unified
+ * configuration cascade and tool delegation.
+ */
+import type { AgentConfig, PromptOverrides, TokenUsage, AgentResponse } from '../types/index.js';
+import type { Prompt } from './prompt.js';
+import { MCPHandler } from './mcp-handler.js';
+import type { AsyncStream } from '../types/streaming.js';
+/**
+ * Result from a prompt execution including metadata
+ */
+export interface PromptResult<T> {
+    /** Validated response data */
+    data: T;
+    /** Token usage from the API */
+    usage: TokenUsage;
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Number of tool invocations */
+    toolCalls: number;
+}
+/**
+ * Agent class - executes prompts via Anthropic Agent SDK
+ */
+export declare class Agent {
+    /** Unique identifier for this agent instance */
+    readonly id: string;
+    /** Agent name */
+    readonly name: string;
+    /** Stored configuration */
+    private readonly config;
+    /** MCP handler for tool management */
+    private readonly mcpHandler;
+    /** Direct MCPHandler instances for delegated execution */
+    private readonly mcpHandlers;
+    /** Default model to use */
+    private readonly model;
+    /** Harness to use for this agent (resolved at construction) */
+    private readonly harnessId?;
+    /** Harness-specific options for this agent */
+    private readonly harnessOptions?;
+    /** Harness instance from registry (resolved at construction) */
+    private readonly harness;
+    /**
+     * Create a new Agent instance
+     * @param config Agent configuration (default: { name: 'Agent', model: 'claude-sonnet-4-20250514' })
+     */
+    constructor(config?: AgentConfig);
+    /**
+     * Execute tool via MCPHandler delegation
+     *
+     * This method implements the ToolExecutor callback signature for provider
+     * integration. Providers delegate tool execution back to the Agent's
+     * MCPHandler, maintaining centralized tool management.
+     *
+     * Tool names use the serverName__toolName format (double underscore)
+     * created during MCP server registration. The full name is passed
+     * directly to MCPHandler without parsing.
+     *
+     * ## Tool Resolution Order
+     *
+     * 1. Delegated handlers (this.mcpHandlers[]) - Custom MCPHandler instances
+     * 2. Main handler (this.mcpHandler) - Primary tool registry
+     *
+     * ## Error Handling
+     *
+     * Tool errors are returned in ToolExecutionResult format with isError: true.
+     * The method never throws - errors are wrapped in result objects.
+     *
+     * @param req - Tool execution request with name (serverName__toolName) and input
+     * @returns Promise resolving to tool execution result with content and error flag
+     * @private
+     * @remarks
+     * Used internally by provider.execute() for tool delegation.
+     * Tool execution flow: Provider → Agent.toolExecutor → MCPHandler.executeTool()
+     */
+    private toolExecutor;
+    /**
+     * Convert MCPHandler ToolResult to ToolExecutionResult
+     *
+     * Maps the MCPHandler's internal ToolResult format to the
+     * provider-facing ToolExecutionResult format.
+     *
+     * Tries to parse JSON strings back to objects for better usability.
+     *
+     * @param toolResult - Result from MCPHandler.executeTool()
+     * @returns ToolExecutionResult with content and isError flag
+     * @private
+     */
+    private convertToToolExecutionResult;
+    /**
+     * Execute a prompt and return validated response
+     * @param prompt Prompt to execute (required)
+     * @param overrides Optional overrides for this execution (default: undefined)
+     * @returns AgentResponse containing validated response or error
+     */
+    prompt<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<AgentResponse<T>>;
+    /**
+     * Execute a prompt with full result metadata
+     * @param prompt Prompt to execute
+     * @param overrides Optional overrides for this execution
+     * @returns Full result including metadata
+     * @deprecated Use prompt() which now returns AgentResponse with metadata
+     */
+    promptWithMetadata<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<PromptResult<T>>;
+    /**
+     * Execute a prompt with reflection capabilities
+     * @param prompt Prompt to execute (required)
+     * @param overrides Optional overrides for this execution (default: undefined)
+     * @returns AgentResponse containing validated response or error
+     * @remarks Reflection follows opt-out pattern: enabled by default unless explicitly disabled.
+     * When reflection is enabled (prompt.enableReflection, overrides.enableReflection, or
+     * config.enableReflection), prefixes system prompt with reflection instructions.
+     */
+    reflect<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<AgentResponse<T>>;
+    /**
+     * Execute a prompt with streaming response
+     *
+     * Returns an AsyncStream that yields StreamEvent objects during execution.
+     * Enables real-time response generation with text deltas, tool calls, and metadata.
+     *
+     * @param prompt Prompt to execute
+     * @param overrides Optional overrides for this execution
+     * @returns AsyncStream with AsyncGenerator for for-await...of consumption
+     *
+     * @example
+     * ```ts
+     * const agent = new Agent({ provider: 'anthropic' });
+     * const prompt = new Prompt({ user: 'Tell me a story' });
+     *
+     * const streamResult = agent.stream(prompt);
+     *
+     * for await (const event of streamResult.stream) {
+     *   switch (event.type) {
+     *     case 'text_delta':
+     *       process.stdout.write(event.delta);
+     *       break;
+     *     case 'tool_call_start':
+     *       console.log(`Tool: ${event.name}`);
+     *       break;
+     *     case 'done':
+     *       console.log('Complete!');
+     *       break;
+     *     case 'error':
+     *       console.error('Error:', event.error.message);
+     *       break;
+     *   }
+     * }
+     * ```
+     */
+    stream<T>(prompt: Prompt<T>, overrides?: PromptOverrides): AsyncStream<T>;
+    /**
+     * Get the MCP handler for custom tool registration
+     */
+    getMcpHandler(): MCPHandler;
+    /**
+     * Emit an event if within workflow context
+     */
+    private emitWorkflowEvent;
+    /**
+     * Internal prompt execution with full flow using provider abstraction
+     * @side effects May emit workflow events, may read from/write to cache if enabled,
+     * may modify environment variables temporarily, validates response against schema,
+     * and stores result in cache if enabled.
+     */
+    private executePrompt;
+    /**
+     * Validates an AgentResponse against the schema before returning
+     *
+     * This provides defense-in-depth validation to ensure all returned responses
+     * conform to the AgentResponse schema, even if factory helpers have bugs.
+     *
+     * @template T - The type of response data
+     * @param response - The response to validate (required)
+     * @param dataSchema - The Zod schema for the response data (required from Prompt.responseFormat)
+     * @returns The validated response, or an INTERNAL_ERROR response if validation fails
+     *
+     * @private
+     */
+    private validateResponse;
+    /**
+     * Merge tools from config and MCP servers
+     */
+    private mergeTools;
+    /**
+     * Merge hooks from multiple sources
+     */
+    private mergeHooks;
+    /**
+     * Set up environment variables
+     * @side effects Modifies process.env with provided values and returns original values for restoration.
+     * Restores environment in finally block of executePrompt.
+     */
+    private setupEnvironment;
+    /**
+     * Restore environment variables
+     */
+    private restoreEnvironment;
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EAGf,UAAU,EAMV,aAAa,EAEd,MAAM,mBAAmB,CAAC;AAK3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAkB9C,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,uBAAuB,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,8BAA8B;IAC9B,IAAI,EAAE,CAAC,CAAC;IACR,+BAA+B;IAC/B,KAAK,EAAE,UAAU,CAAC;IAClB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,KAAK;IAChB,gDAAgD;IAChD,SAAgB,EAAE,EAAE,MAAM,CAAC;IAE3B,iBAAiB;IACjB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,2BAA2B;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAEhD,2BAA2B;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAY;IAEvC,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;IAEjD,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC;;;OAGG;gBACS,MAAM,GAAE,WAAgB;IA0DpC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;YACW,YAAY;IA+B1B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,4BAA4B;IA4BpC;;;;;OAKG;IACU,MAAM,CAAC,CAAC,EACnB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,SAAS,CAAC,EAAE,eAAe,GAC1B,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAI5B;;;;;;OAMG;IACU,kBAAkB,CAAC,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,SAAS,CAAC,EAAE,eAAe,GAC1B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAc3B;;;;;;;;OAQG;IACU,OAAO,CAAC,CAAC,EACpB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,SAAS,CAAC,EAAE,eAAe,GAC1B,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAqB5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACI,MAAM,CAAC,CAAC,EACb,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,SAAS,CAAC,EAAE,eAAe,GAC1B,WAAW,CAAC,CAAC,CAAC;IAyNjB;;OAEG;IACI,aAAa,IAAI,UAAU;IAIlC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;OAKG;YACW,aAAa;IAgV3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,gBAAgB;IAyCxB;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACH,OAAO,CAAC,UAAU;IA6BlB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAS3B"}