groundswell 0.0.3 → 1.0.0

package/dist/core/agent.js

@@ -1,16 +1,21 @@
 /**
- * Agent - Lightweight wrapper around Anthropic's Agent SDK
+ * Agent - Multi-provider agent for LLM prompt execution
  *
- * Agents execute prompts and manage tool invocation cycles.
- * All configuration properties map 1:1 to Anthropic SDK.
+ * Agents execute prompts via provider abstraction layer, supporting
+ * multiple LLM providers (Anthropic, Claude Code, etc.) with unified
+ * configuration cascade and tool delegation.
  */
-import Anthropic from '@anthropic-ai/sdk';
+import { createSuccessResponse, createErrorResponse, } from '../types/index.js';
 import { MCPHandler } from './mcp-handler.js';
 import { generateId } from '../utils/id.js';
+import { validateAgentResponse } from '../utils/agent-validation.js';
 import { getExecutionContext } from './context.js';
 import { generateCacheKey, defaultCache } from '../cache/index.js';
+import { HarnessRegistry, registerDefaultHarnesses } from '../harnesses/index.js';
+import { getGlobalHarnessConfig, resolveHarnessConfig } from '../utils/harness-config.js';
+import { parseModelSpec } from '../utils/model-spec.js';
 /**
- * Agent class - executes prompts via Anthropic SDK
+ * Agent class - executes prompts via Anthropic Agent SDK
  */
 export class Agent {
     /** Unique identifier for this agent instance */
@@ -19,27 +24,55 @@ export class Agent {
     name;
     /** Stored configuration */
     config;
-    /** Anthropic client instance */
-    client;
     /** MCP handler for tool management */
     mcpHandler;
     /** Direct MCPHandler instances for delegated execution */
     mcpHandlers = [];
     /** Default model to use */
     model;
+    /** Harness to use for this agent (resolved at construction) */
+    harnessId;
+    /** Harness-specific options for this agent */
+    harnessOptions;
+    /** Harness instance from registry (resolved at construction) */
+    harness;
     /**
      * Create a new Agent instance
-     * @param config Agent configuration
+     * @param config Agent configuration (default: { name: 'Agent', model: 'claude-sonnet-4-20250514' })
      */
     constructor(config = {}) {
         this.id = generateId();
         this.name = config.name ?? 'Agent';
         this.config = config;
         this.model = config.model ?? 'claude-sonnet-4-20250514';
-        // Create Anthropic client
-        this.client = new Anthropic({
-            apiKey: process.env.ANTHROPIC_API_KEY,
-        });
+        // Store harness configuration from AgentConfig (PRD §7.9).
+        // Backward-compat bridge: prefer the new `harness` field; fall back to the legacy `provider`
+        // field so existing callers (`new Agent({ provider: 'anthropic' })`) keep working during the
+        // v1.2 migration. The fallback + legacy global-config singleton are removed by T2 (P3.M1.T2)
+        // when executePrompt/stream + the test suite move to configureHarnesses/getGlobalHarnessConfig.
+        this.harnessId = config.harness ?? config.provider;
+        this.harnessOptions = config.harnessOptions ?? config.providerOptions;
+        // Resolve the effective harness via the configuration cascade (PRD §7.7).
+        // getGlobalHarnessConfig reads the correct singleton (default 'pi') written by configureHarnesses().
+        const globalConfig = getGlobalHarnessConfig();
+        const resolved = resolveHarnessConfig(globalConfig, this.harnessId, this.harnessOptions);
+        const effectiveHarness = resolved.harness;
+        // Fetch the harness instance from HarnessRegistry (the v1.2 rename of ProviderRegistry).
+        // The cast bridges the legacy Provider return type to the Harness contract — structurally
+        // identical at runtime; the cast exists only because Provider.id is a wider type than Harness.id.
+        const registry = HarnessRegistry.getInstance();
+        let harnessInstance = registry.get(effectiveHarness);
+        // Lazy auto-registration safety net (PRD §7.6 / Issue 4 h3.3): if the resolved harness is a
+        // built-in default ('pi' | 'claude-code') that isn't registered yet, materialize the defaults
+        // once. registerDefaultHarnesses is idempotent (has() guards) → never overwrites a test's mock.
+        if (!harnessInstance && (effectiveHarness === 'pi' || effectiveHarness === 'claude-code')) {
+            registerDefaultHarnesses(registry);
+            harnessInstance = registry.get(effectiveHarness);
+        }
+        if (!harnessInstance) {
+            throw new Error(`Harness '${effectiveHarness}' is not registered`);
+        }
+        this.harness = harnessInstance;
         // Initialize MCP handler
         this.mcpHandler = new MCPHandler();
         // Register MCP servers
@@ -55,30 +88,133 @@ export class Agent {
             }
         }
     }
+    /**
+     * 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()
+     */
+    async toolExecutor(req) {
+        try {
+            // Check delegated MCPHandlers first (preserve custom executors)
+            for (const handler of this.mcpHandlers) {
+                if (handler.hasTool(req.name)) {
+                    const toolResult = await handler.executeTool(req.name, req.input);
+                    return this.convertToToolExecutionResult(toolResult);
+                }
+            }
+            // Check main MCPHandler
+            if (this.mcpHandler.hasTool(req.name)) {
+                const toolResult = await this.mcpHandler.executeTool(req.name, req.input);
+                return this.convertToToolExecutionResult(toolResult);
+            }
+            // Tool not found in any handler
+            return {
+                content: `Tool '${req.name}' not found`,
+                isError: true,
+            };
+        }
+        catch (error) {
+            // Handle unexpected errors (defensive programming)
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: `Tool execution error: ${message}`,
+                isError: true,
+            };
+        }
+    }
+    /**
+     * 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
+     */
+    convertToToolExecutionResult(toolResult) {
+        let content = toolResult.content;
+        // If content is a string, try to parse it as JSON
+        // This restores objects that were stringified by MCPHandler.executeTool()
+        if (typeof content === 'string') {
+            try {
+                const parsed = JSON.parse(content);
+                // Only use parsed value if it's an object or array (not primitive)
+                if (typeof parsed === 'object' && parsed !== null) {
+                    content = parsed;
+                }
+            }
+            catch {
+                // Content is not valid JSON, keep original string
+            }
+        }
+        return {
+            content,
+            isError: toolResult.is_error ?? false,
+        };
+    }
     /**
      * Execute a prompt and return validated response
-     * @param prompt Prompt to execute
-     * @param overrides Optional overrides for this execution
-     * @returns Validated response of type T
+     * @param prompt Prompt to execute (required)
+     * @param overrides Optional overrides for this execution (default: undefined)
+     * @returns AgentResponse containing validated response or error
      */
     async prompt(prompt, overrides) {
-        const result = await this.executePrompt(prompt, overrides);
-        return result.data;
+        return this.executePrompt(prompt, overrides);
     }
     /**
      * 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
      */
     async promptWithMetadata(prompt, overrides) {
-        return this.executePrompt(prompt, overrides);
+        const response = await this.executePrompt(prompt, overrides);
+        // Convert AgentResponse back to PromptResult for backward compatibility
+        if (response.status === 'error') {
+            throw new Error(response.error?.message ?? 'Unknown error');
+        }
+        return {
+            data: response.data, // Type assertion: data is T when status is not 'error'
+            usage: response.metadata.usage ?? { input_tokens: 0, output_tokens: 0 },
+            duration: response.metadata.duration ?? 0,
+            toolCalls: response.metadata.toolCalls ?? 0,
+        };
     }
     /**
      * Execute a prompt with reflection capabilities
-     * @param prompt Prompt to execute
-     * @param overrides Optional overrides for this execution
-     * @returns Validated response of type T
+     * @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.
      */
     async reflect(prompt, overrides) {
         // Add reflection system prefix if reflection is enabled
@@ -93,8 +229,210 @@ export class Agent {
             system: systemPrefix +
                 (prompt.systemOverride ?? overrides?.system ?? this.config.system ?? ''),
         };
-        const result = await this.executePrompt(prompt, effectiveOverrides);
-        return result.data;
+        return this.executePrompt(prompt, effectiveOverrides);
+    }
+    /**
+     * 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(prompt, overrides) {
+        // Extract prompt-level harness overrides (PRD §7.7, §7.9).
+        // Backward-compat bridge: prefer the new `harness` field; fall back to the legacy `provider`
+        // field so existing callers (`agent.stream(p, { provider: 'claude-code' })`) keep working during
+        // the v1.2 migration. The fallback + legacy global-config singleton are removed once
+        // PromptOverrides + the test suite are fully on harness vocabulary (later lockstep milestone).
+        const promptHarness = overrides?.harness ?? overrides?.provider;
+        const promptHarnessOptions = overrides?.harnessOptions ?? overrides?.providerOptions;
+        // Resolve the effective harness via the configuration cascade (PRD §7.7): global → agent → prompt.
+        // getGlobalHarnessConfig reads the correct singleton (default 'pi') written by configureHarnesses().
+        const globalConfig = getGlobalHarnessConfig();
+        const { harness: resolvedHarness, options: resolvedHarnessOptions } = resolveHarnessConfig(globalConfig, this.harnessId, this.harnessOptions, promptHarness, promptHarnessOptions);
+        // Fetch the harness instance from HarnessRegistry (may differ from this.harness when a prompt
+        // override is supplied). The cast bridges the legacy Provider return type to the Harness contract
+        // — structurally identical at runtime; the cast exists only because Provider.id is wider than Harness.id.
+        const registry = HarnessRegistry.getInstance();
+        let harnessInstance = registry.get(resolvedHarness);
+        // Lazy auto-registration safety net (PRD §7.6 / Issue 4 h3.3): if the resolved harness is a
+        // built-in default ('pi' | 'claude-code') that isn't registered yet, materialize the defaults
+        // once. registerDefaultHarnesses is idempotent (has() guards) → never overwrites a test's mock.
+        if (!harnessInstance && (resolvedHarness === 'pi' || resolvedHarness === 'claude-code')) {
+            registerDefaultHarnesses(registry);
+            harnessInstance = registry.get(resolvedHarness);
+        }
+        if (!harnessInstance) {
+            // THROW (synchronous at call time, before the generator is created) — preserves the existing
+            // .rejects.toThrow(...) contract. Reworded to harness vocab; message still contains the id +
+            // 'is not registered' so the updated legacy-test regex still matches.
+            throw new Error(`Harness '${resolvedHarness}' is not registered`);
+        }
+        // Capture non-null harness instance for use in closure (TypeScript strict mode requirement)
+        const harness = harnessInstance;
+        // Merge configuration: Prompt > Overrides > Config
+        const effectiveSystem = prompt.systemOverride ?? overrides?.system ?? this.config.system;
+        const effectiveModel = overrides?.model ?? this.model;
+        const effectiveMaxTokens = overrides?.maxTokens ?? this.config.maxTokens ?? 4096;
+        const effectiveTemperature = overrides?.temperature ?? this.config.temperature;
+        const effectiveTools = this.mergeTools(prompt.toolsOverride ?? overrides?.tools ?? this.config.tools);
+        const effectiveHooks = this.mergeHooks(prompt.hooksOverride, overrides?.hooks, this.config.hooks);
+        // Build user message
+        const userMessage = prompt.buildUserMessage();
+        // Convert Agent.hooks to HarnessHookEvents
+        const harnessHooks = {};
+        if (effectiveHooks.preToolUse && effectiveHooks.preToolUse.length > 0) {
+            harnessHooks.onToolStart = async (tool) => {
+                for (const hook of effectiveHooks.preToolUse) {
+                    await hook({
+                        toolName: tool.name,
+                        toolInput: tool.input,
+                        agentId: this.id,
+                    });
+                }
+            };
+        }
+        if (effectiveHooks.postToolUse && effectiveHooks.postToolUse.length > 0) {
+            harnessHooks.onToolEnd = async (tool, result, duration) => {
+                for (const hook of effectiveHooks.postToolUse) {
+                    await hook({
+                        toolName: tool.name,
+                        toolInput: tool.input,
+                        toolOutput: result.content,
+                        agentId: this.id,
+                        duration,
+                    });
+                }
+            };
+        }
+        if (effectiveHooks.sessionStart && effectiveHooks.sessionStart.length > 0) {
+            harnessHooks.onSessionStart = async () => {
+                for (const hook of effectiveHooks.sessionStart) {
+                    await hook({
+                        agentId: this.id,
+                        agentName: this.name,
+                    });
+                }
+            };
+        }
+        if (effectiveHooks.sessionEnd && effectiveHooks.sessionEnd.length > 0) {
+            harnessHooks.onSessionEnd = async (totalDuration) => {
+                for (const hook of effectiveHooks.sessionEnd) {
+                    await hook({
+                        agentId: this.id,
+                        agentName: this.name,
+                        totalDuration,
+                    });
+                }
+            };
+        }
+        // Create AbortController for cancellation support
+        const controller = new AbortController();
+        // Build HarnessRequest with streaming enabled (PRD §7.3, §7.4). Identical shape to the legacy
+        // ProviderRequest — the swap is a type rename (ProviderRequest = HarnessRequest alias).
+        // streaming: true flips Harness.execute into AsyncGenerator mode.
+        const harnessRequest = {
+            prompt: userMessage,
+            options: {
+                model: effectiveModel,
+                systemPrompt: effectiveSystem,
+                tools: effectiveTools,
+                sessionId: resolvedHarnessOptions.sessionId,
+                hooks: harnessHooks,
+                streaming: true, // CRITICAL: Enable streaming mode
+            },
+        };
+        // Create async generator that wraps harness streaming
+        const self = this;
+        async function* streamGenerator() {
+            try {
+                // Call harness with streaming enabled
+                // Harness returns: Promise<AgentResponse<T>> | AsyncGenerator<StreamEvent, AgentResponse<T>>
+                const harnessResult = harness.execute(harnessRequest, self.toolExecutor.bind(self), harnessHooks);
+                // Check if harness returned an AsyncGenerator (streaming mode) directly
+                if (Symbol.asyncIterator in harnessResult) {
+                    // Harness is in streaming mode - iterate and yield events
+                    const harnessStream = harnessResult;
+                    let finalValue;
+                    for await (const event of harnessStream) {
+                        // Check for cancellation
+                        if (controller.signal.aborted) {
+                            yield {
+                                type: 'error',
+                                error: new Error('Stream cancelled'),
+                                code: 'CANCELLED',
+                                retryable: false,
+                            };
+                            // Cancellation: return error response
+                            return createErrorResponse('CANCELLED', 'Stream cancelled by user', {}, false);
+                        }
+                        // Yield event from harness
+                        yield event;
+                    }
+                    // After loop completes, the AsyncGenerator's return value is the final AgentResponse<T>
+                    // We need to get it by calling next() one more time
+                    const finalResult = await harnessStream.next();
+                    // The value should be AgentResponse<T> when done=true, but TypeScript sees it as StreamEvent | AgentResponse<T>
+                    finalValue = finalResult.value;
+                    // Return the final response
+                    return finalValue;
+                }
+                else {
+                    // Provider returned a Promise<AgentResponse<T>> (non-streaming mode)
+                    // This shouldn't happen with streaming: true, but handle it gracefully
+                    const responsePromise = harnessResult;
+                    const response = await responsePromise;
+                    yield {
+                        type: 'done',
+                        finishReason: response.status === 'error' ? 'error' : 'stop',
+                    };
+                    return response;
+                }
+            }
+            catch (error) {
+                // Yield error event instead of throwing
+                yield {
+                    type: 'error',
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    code: 'STREAM_ERROR',
+                    retryable: false,
+                };
+                // Return error response for AsyncGenerator completion
+                return createErrorResponse('STREAM_ERROR', error instanceof Error ? error.message : String(error), {}, false);
+            }
+        }
+        return {
+            stream: streamGenerator.call(this),
+            controller,
+        };
     }
     /**
      * Get the MCP handler for custom tool registration
@@ -112,14 +450,44 @@ export class Agent {
         }
     }
     /**
-     * Internal prompt execution with full flow
+     * 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.
      */
     async executePrompt(prompt, overrides) {
         const startTime = Date.now();
-        let toolCallCount = 0;
-        let totalUsage = { input_tokens: 0, output_tokens: 0 };
+        const requestId = generateId();
         // Get execution context for event emission
         const ctx = getExecutionContext();
+        // Extract prompt-level harness overrides (PRD §7.7, §7.9).
+        // Backward-compat bridge: prefer the new `harness` field; fall back to the legacy `provider`
+        // field so existing callers (`agent.prompt(p, { provider: 'claude-code' })`) keep working during
+        // the v1.2 migration. The fallback + legacy global-config singleton are removed once
+        // PromptOverrides + the test suite are fully on harness vocabulary (later lockstep milestone).
+        const promptHarness = overrides?.harness ?? overrides?.provider;
+        const promptHarnessOptions = overrides?.harnessOptions ?? overrides?.providerOptions;
+        // Resolve the effective harness via the configuration cascade (PRD §7.7): global → agent → prompt.
+        // getGlobalHarnessConfig reads the correct singleton (default 'pi') written by configureHarnesses().
+        const globalConfig = getGlobalHarnessConfig();
+        const { harness: resolvedHarness, options: resolvedHarnessOptions } = resolveHarnessConfig(globalConfig, this.harnessId, this.harnessOptions, promptHarness, promptHarnessOptions);
+        // Fetch the harness instance from HarnessRegistry (may differ from this.harness when a prompt
+        // override is supplied). The cast bridges the legacy Provider return type to the Harness contract
+        // — structurally identical at runtime; the cast exists only because Provider.id is wider than Harness.id.
+        const registry = HarnessRegistry.getInstance();
+        let harnessInstance = registry.get(resolvedHarness);
+        // Lazy auto-registration safety net (PRD §7.6 / Issue 4 h3.3): if the resolved harness is a
+        // built-in default ('pi' | 'claude-code') that isn't registered yet, materialize the defaults
+        // once. registerDefaultHarnesses is idempotent (has() guards) → never overwrites a test's mock.
+        if (!harnessInstance && (resolvedHarness === 'pi' || resolvedHarness === 'claude-code')) {
+            registerDefaultHarnesses(registry);
+            harnessInstance = registry.get(resolvedHarness);
+        }
+        if (!harnessInstance) {
+            return createErrorResponse('PROVIDER_NOT_FOUND', `Harness '${resolvedHarness}' is not registered`, { harnessId: resolvedHarness }, false);
+        }
+        // Capture non-null harness instance for use in closure (TypeScript strict mode requirement)
+        const harness = harnessInstance;
         // Merge configuration: Prompt > Overrides > Config
         const effectiveSystem = prompt.systemOverride ?? overrides?.system ?? this.config.system;
         const effectiveModel = overrides?.model ?? this.model;
@@ -129,11 +497,20 @@ export class Agent {
         const cacheEnabled = this.config.enableCache && !overrides?.disableCache;
         let cacheKey;
         if (cacheEnabled) {
+            // PRD §7.14.5: isolate cache entries per (harness, provider, model).
+            // - harness: the resolved HarnessId (PRD §7.7 cascade, resolved above).
+            // - provider: the LLM host parsed from the effective model spec (PRD §7.8). Bare models
+            //   resolve against the global defaultModelProvider (defaults to 'anthropic' when unset).
+            //   NOTE: parseModelSpec throws on invalid model strings — intentional fail-fast.
+            const defaultModelProvider = getGlobalHarnessConfig().defaultModelProvider;
+            const modelSpec = parseModelSpec(effectiveModel, defaultModelProvider);
             const cacheInputs = {
                 user: prompt.buildUserMessage(),
                 data: prompt.getData(),
                 system: effectiveSystem,
                 model: effectiveModel,
+                harness: resolvedHarness, // PRD §7.14.5 — harness axis (ProviderId ⊃ HarnessId; cast safe)
+                provider: modelSpec.provider, // PRD §7.14.5 — LLM provider axis (from ModelSpec, §7.8)
                 temperature: effectiveTemperature,
                 maxTokens: effectiveMaxTokens,
                 tools: this.config.tools,
@@ -143,7 +520,8 @@ export class Agent {
             };
             cacheKey = generateCacheKey(cacheInputs);
             const cached = await defaultCache.get(cacheKey);
-            if (cached) {
+            if (cached && 'status' in cached) {
+                // New AgentResponse format - has 'status' field
                 // Emit cache hit event
                 if (ctx) {
                     this.emitWorkflowEvent({
@@ -154,6 +532,7 @@ export class Agent {
                 }
                 return cached;
             }
+            // Old PromptResult format or undefined - re-execute
             // Emit cache miss event
             if (ctx) {
                 this.emitWorkflowEvent({
@@ -175,91 +554,143 @@ export class Agent {
         }
         const effectiveTools = this.mergeTools(prompt.toolsOverride ?? overrides?.tools ?? this.config.tools);
         const effectiveHooks = this.mergeHooks(prompt.hooksOverride, overrides?.hooks, this.config.hooks);
-        const effectiveStop = overrides?.stop;
         // Set up environment variables
         const originalEnv = this.setupEnvironment(overrides?.env ?? this.config.env);
         try {
-            // Call session start hooks
-            await this.callHooks(effectiveHooks?.sessionStart, {
-                agentId: this.id,
-                agentName: this.name,
-            });
-            // Build initial messages
-            const messages = [
-                { role: 'user', content: prompt.buildUserMessage() },
-            ];
-            // Execute conversation loop
-            let response = await this.callApi(messages, effectiveSystem, effectiveTools, effectiveModel, effectiveMaxTokens, effectiveTemperature, effectiveStop);
-            totalUsage = this.addUsage(totalUsage, response.usage);
-            // Handle tool use loop
-            while (response.stop_reason === 'tool_use') {
-                const toolUseBlocks = response.content.filter((block) => block.type === 'tool_use');
-                const toolResults = [];
-                for (const toolUse of toolUseBlocks) {
-                    toolCallCount++;
-                    // Call pre-tool hooks
-                    await this.callHooks(effectiveHooks?.preToolUse, {
-                        toolName: toolUse.name,
-                        toolInput: toolUse.input,
-                        agentId: this.id,
-                    });
-                    const toolStartTime = Date.now();
-                    // Execute tool
-                    const result = await this.executeTool(toolUse.name, toolUse.input);
-                    const toolDuration = Date.now() - toolStartTime;
-                    // Emit tool invocation event if in workflow context
-                    if (ctx) {
-                        this.emitWorkflowEvent({
-                            type: 'toolInvocation',
-                            toolName: toolUse.name,
-                            input: toolUse.input,
-                            output: result,
-                            duration: toolDuration,
-                            node: ctx.workflowNode,
+            // Build user message
+            const userMessage = prompt.buildUserMessage();
+            // Convert AgentHooks → HarnessHookEvents (identical wiring, retyped).
+            const harnessHooks = {};
+            if (effectiveHooks.preToolUse && effectiveHooks.preToolUse.length > 0) {
+                harnessHooks.onToolStart = async (tool) => {
+                    for (const hook of effectiveHooks.preToolUse) {
+                        await hook({
+                            toolName: tool.name,
+                            toolInput: tool.input,
+                            agentId: this.id,
+                        });
+                    }
+                };
+            }
+            if (effectiveHooks.postToolUse && effectiveHooks.postToolUse.length > 0) {
+                harnessHooks.onToolEnd = async (tool, result, duration) => {
+                    for (const hook of effectiveHooks.postToolUse) {
+                        await hook({
+                            toolName: tool.name,
+                            toolInput: tool.input,
+                            toolOutput: result.content,
+                            agentId: this.id,
+                            duration,
+                        });
+                    }
+                };
+            }
+            if (effectiveHooks.sessionStart && effectiveHooks.sessionStart.length > 0) {
+                harnessHooks.onSessionStart = async () => {
+                    for (const hook of effectiveHooks.sessionStart) {
+                        await hook({
+                            agentId: this.id,
+                            agentName: this.name,
                         });
                     }
-                    // Call post-tool hooks
-                    await this.callHooks(effectiveHooks?.postToolUse, {
-                        toolName: toolUse.name,
-                        toolInput: toolUse.input,
-                        toolOutput: result,
+                };
+            }
+            if (effectiveHooks.sessionEnd && effectiveHooks.sessionEnd.length > 0) {
+                harnessHooks.onSessionEnd = async (totalDuration) => {
+                    for (const hook of effectiveHooks.sessionEnd) {
+                        await hook({
+                            agentId: this.id,
+                            agentName: this.name,
+                            totalDuration,
+                        });
+                    }
+                };
+            }
+            // Build HarnessRequest with nested structure (PRD §7.3). Identical shape to the legacy
+            // ProviderRequest — the swap is a type rename (ProviderRequest = HarnessRequest alias).
+            const harnessRequest = {
+                prompt: userMessage,
+                options: {
+                    model: effectiveModel,
+                    systemPrompt: effectiveSystem,
+                    tools: effectiveTools,
+                    sessionId: resolvedHarnessOptions.sessionId,
+                    hooks: harnessHooks,
+                },
+            };
+            // Execute via the Harness abstraction (PRD §7.3).
+            // Harness returns: Promise<AgentResponse<T>> | AsyncGenerator<StreamEvent, AgentResponse<T>>
+            // For non-streaming mode, it returns Promise<AgentResponse<T>>.
+            const harnessResult = harness.execute(harnessRequest, this.toolExecutor.bind(this), harnessHooks);
+            // Handle the union return type
+            const response = Symbol.asyncIterator in harnessResult
+                ? (await (async () => {
+                    // Harness returned AsyncGenerator (shouldn't happen without streaming: true, but handle gracefully)
+                    const generator = harnessResult;
+                    // Consume all events
+                    for await (const _event of generator) {
+                        // Discard events, we just want the final response
+                    }
+                    const finalResult = await generator.next();
+                    // The value should be AgentResponse<T> when done=true
+                    return finalResult.value;
+                })())
+                : await harnessResult;
+            const duration = Date.now() - startTime;
+            // Handle error response from provider
+            if (response.status === 'error') {
+                // Emit prompt end event if in workflow context
+                if (ctx) {
+                    this.emitWorkflowEvent({
+                        type: 'agentPromptEnd',
                         agentId: this.id,
-                        duration: toolDuration,
-                    });
-                    toolResults.push({
-                        type: 'tool_result',
-                        tool_use_id: toolUse.id,
-                        content: typeof result === 'string' ? result : JSON.stringify(result),
+                        agentName: this.name,
+                        promptId: prompt.id,
+                        node: ctx.workflowNode,
+                        duration,
                     });
                 }
-                // Add assistant message with tool uses
-                messages.push({ role: 'assistant', content: response.content });
-                // Add tool results
-                messages.push({ role: 'user', content: toolResults });
-                // Continue conversation
-                response = await this.callApi(messages, effectiveSystem, effectiveTools, effectiveModel, effectiveMaxTokens, effectiveTemperature, effectiveStop);
-                totalUsage = this.addUsage(totalUsage, response.usage);
+                return response;
             }
-            // Extract text response
-            const textContent = response.content.find((block) => block.type === 'text');
-            if (!textContent) {
-                throw new Error('No text response received from API');
+            // Validate structured output if prompt has schema
+            let validatedResponse;
+            if (prompt.getResponseFormat()) {
+                const validationResult = prompt.safeValidateResponse(response.data);
+                if (validationResult.success) {
+                    // Update metadata with agent ID instead of provider ID
+                    const metadata = {
+                        ...response.metadata,
+                        agentId: this.id,
+                    };
+                    validatedResponse = createSuccessResponse(validationResult.data, metadata);
+                }
+                else {
+                    const zodError = validationResult.error;
+                    const errorSummary = zodError.errors
+                        .map((err) => {
+                        const field = err.path.length > 0 ? err.path.join('.') : 'response';
+                        return `${field}: ${err.message}`;
+                    })
+                        .join('; ');
+                    validatedResponse = createErrorResponse('VALIDATION_ERROR', `Response validation failed: ${errorSummary}`, {
+                        validationErrors: zodError.errors.map((err) => ({
+                            field: err.path.join('.') || 'root',
+                            message: err.message,
+                            code: err.code,
+                        })),
+                    }, false);
+                }
             }
-            // Parse JSON from response
-            const jsonMatch = textContent.text.match(/\{[\s\S]*\}/);
-            if (!jsonMatch) {
-                throw new Error('No JSON object found in response');
+            else {
+                // No validation schema - use provider response as-is
+                validatedResponse = {
+                    ...response,
+                    metadata: {
+                        ...response.metadata,
+                        agentId: this.id,
+                    },
+                };
             }
-            const parsed = JSON.parse(jsonMatch[0]);
-            // Validate with schema
-            const validated = prompt.validateResponse(parsed);
-            // Call session end hooks
-            await this.callHooks(effectiveHooks?.sessionEnd, {
-                agentId: this.id,
-                agentName: this.name,
-                totalDuration: Date.now() - startTime,
-            });
-            const duration = Date.now() - startTime;
             // Emit prompt end event if in workflow context
             if (ctx) {
                 this.emitWorkflowEvent({
@@ -269,20 +700,22 @@ export class Agent {
                     promptId: prompt.id,
                     node: ctx.workflowNode,
                     duration,
-                    tokenUsage: totalUsage,
+                    tokenUsage: validatedResponse.metadata.usage,
                 });
             }
-            const result = {
-                data: validated,
-                usage: totalUsage,
-                duration,
-                toolCalls: toolCallCount,
-            };
+            // Validate before returning (defense-in-depth)
+            const finalResponse = this.validateResponse(validatedResponse, prompt.responseFormat);
             // Store in cache if enabled
             if (cacheEnabled && cacheKey) {
-                await defaultCache.set(cacheKey, result, { prefix: this.id });
+                await defaultCache.set(cacheKey, finalResponse, { prefix: this.id });
             }
-            return result;
+            return finalResponse;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return createErrorResponse('PROVIDER_EXECUTION_FAILED', `Harness execution error: ${message}`, { duration, harnessId: resolvedHarness }, true // Provider errors are typically recoverable
+            );
         }
         finally {
             // Restore environment
@@ -290,56 +723,47 @@ export class Agent {
         }
     }
     /**
-     * Call the Anthropic API
+     * 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
      */
-    async callApi(messages, system, tools, model, maxTokens, temperature, stop) {
-        const params = {
-            model,
-            max_tokens: maxTokens,
-            messages,
-        };
-        if (system) {
-            params.system = system;
-        }
-        if (tools && tools.length > 0) {
-            params.tools = tools.map((tool) => ({
-                name: tool.name,
-                description: tool.description,
-                input_schema: tool.input_schema,
-            }));
+    validateResponse(response, dataSchema) {
+        // Call shared utility for validation
+        const result = validateAgentResponse(response, dataSchema);
+        if (result.valid) {
+            // Response is valid, return it unchanged
+            return response;
         }
-        if (temperature !== undefined) {
-            params.temperature = temperature;
-        }
-        if (stop && stop.length > 0) {
-            params.stop_sequences = stop;
-        }
-        return this.client.messages.create(params);
-    }
-    /**
-     * Execute a tool (either direct or via MCP)
-     */
-    async executeTool(name, input) {
-        // First, check stored MCPHandler instances (they have registered executors)
-        for (const handler of this.mcpHandlers) {
-            if (handler.hasTool(name)) {
-                const result = await handler.executeTool(name, input);
-                if (result.is_error) {
-                    throw new Error(result.content);
-                }
-                return result.content;
-            }
-        }
-        // Fall back to main mcpHandler (for non-MCPHandler MCPServers)
-        if (this.mcpHandler.hasTool(name)) {
-            const result = await this.mcpHandler.executeTool(name, input);
-            if (result.is_error) {
-                throw new Error(result.content);
-            }
-            return result.content;
-        }
-        // Look for direct tool handler - this would be set by subclasses
-        throw new Error(`No handler found for tool '${name}'`);
+        // Validation failed - this indicates a bug in our code
+        // Log detailed error information for debugging
+        console.error('Agent response validation failed', {
+            agentId: this.id, // Agent-specific logging (not in utility)
+            timestamp: Date.now(),
+            errorCount: result.errors?.errors.length ?? 0,
+            errors: result.errors?.errors.map((err) => ({
+                path: err.path.join('.'),
+                message: err.message,
+                code: err.code,
+            })) ?? [],
+        });
+        // Return INTERNAL_ERROR response
+        // Use createErrorResponse which is already imported
+        return createErrorResponse('INTERNAL_ERROR', 'Internal response validation failed', {
+            validationErrors: result.errors?.errors.map((err) => ({
+                path: err.path.join('.'),
+                message: err.message,
+                code: err.code,
+            })) ?? [],
+        }, false // Non-recoverable - indicates system bug
+        );
     }
     /**
      * Merge tools from config and MCP servers
@@ -377,18 +801,10 @@ export class Agent {
             ],
         };
     }
-    /**
-     * Call hooks of a specific type
-     */
-    async callHooks(hooks, context) {
-        if (!hooks)
-            return;
-        for (const hook of hooks) {
-            await hook(context);
-        }
-    }
     /**
      * 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.
      */
     setupEnvironment(env) {
         if (!env)
@@ -413,14 +829,5 @@ export class Agent {
             }
         }
     }
-    /**
-     * Add token usage from response
-     */
-    addUsage(total, usage) {
-        return {
-            input_tokens: total.input_tokens + usage.input_tokens,
-            output_tokens: total.output_tokens + usage.output_tokens,
-        };
-    }
 }
 //# sourceMappingURL=agent.js.map