groundswell 0.0.3 → 1.0.0

package/dist/types/agent.d.ts

@@ -2,7 +2,10 @@
  * Agent configuration and override types
  * All properties map 1:1 to Anthropic SDK
  */
-import type { Tool, MCPServer, Skill, AgentHooks } from './sdk-primitives.js';
+import type { Tool, MCPServer, Skill, AgentHooks, TokenUsage } from './sdk-primitives.js';
+import type { ProviderId, ProviderOptions } from './providers.js';
+import type { HarnessId, HarnessOptions } from './harnesses.js';
+import { z } from 'zod';
 /**
  * Configuration for creating an Agent instance
  * All Anthropic SDK properties pass through unchanged
@@ -26,12 +29,109 @@ export interface AgentConfig {
     enableReflection?: boolean;
     /** Enable caching of prompt responses */
     enableCache?: boolean;
-    /** Model to use (defaults to claude-sonnet-4-20250514) */
+    /**
+     * Model identifier for LLM inference
+     *
+     * Supports two formats:
+     * - **Plain format**: `"claude-sonnet-4-20250514"` - Uses default provider
+     * - **Qualified format**: `"anthropic/claude-sonnet-4-20250514"` - Explicit provider
+     *
+     * When a plain model name is used (no provider prefix), the provider
+     * is determined by the configuration cascade: prompt override →
+     * agent provider → global default.
+     *
+     * ## Model Specification (PRD 7.8)
+     *
+     * The `parseModelSpec()` utility parses model strings into:
+     * - `provider`: Provider ID (anthropic, claude-code, etc.)
+     * - `model`: Base model name without prefix
+     * - `raw`: Original input string
+     *
+     * @example <caption>Plain format (uses default provider)</caption>
+     * ```ts
+     * const config: AgentConfig = {
+     *   model: 'claude-sonnet-4-20250514'
+     *   // Uses provider from cascade
+     * };
+     * ```
+     *
+     * @example <caption>Qualified format (explicit provider)</caption>
+     * ```ts
+     * const config: AgentConfig = {
+     *   model: 'anthropic/claude-sonnet-4-20250514'
+     *   // Explicitly uses Anthropic provider
+     * };
+     * ```
+     *
+     * @example <caption>Qualified format with Claude Code provider</caption>
+     * ```ts
+     * const config: AgentConfig = {
+     *   model: 'anthropic/claude-sonnet-4'
+     *   // Explicitly uses Anthropic provider
+     * };
+     * ```
+     *
+     * @default "claude-sonnet-4-20250514"
+     * @see {@link parseModelSpec} for model specification parsing
+     * @see {@link ModelSpec} for parsed model structure
+     */
     model?: string;
     /** Maximum tokens for responses */
     maxTokens?: number;
     /** Temperature for response generation */
     temperature?: number;
+    /** Harness to use (inherits from global; default 'pi'). PRD §7.9. */
+    harness?: HarnessId;
+    /** Harness-specific options. PRD §7.9. */
+    harnessOptions?: HarnessOptions;
+    /**
+     * Provider to use for this agent
+     *
+     * @deprecated Since v1.2. Use {@link AgentConfig.harness} (and
+     *   {@link AgentConfig.harnessOptions} for options) instead. The runtime/harness
+     *   axis (`'pi'` | `'claude-code'`) is now independent of the LLM provider/model
+     *   (PRD §7): the harness is chosen separately, and the model string is never
+     *   harness-qualified. Retained for backward compatibility during the v1.2 migration
+     *   and removed when the legacy adapters are renamed/deleted (P2.M1 / P4.M1).
+     *
+     * ```typescript
+     * // BEFORE (v1.x)
+     * const config: AgentConfig = { provider: 'anthropic' };
+     * // AFTER (v1.2)
+     * const config: AgentConfig = {
+     *   harness: 'claude-code',
+     *   model: 'anthropic/claude-sonnet-4-20250514',
+     * };
+     * ```
+     */
+    provider?: ProviderId;
+    /**
+     * Provider-specific options for this agent
+     *
+     * @deprecated Since v1.2. Use {@link AgentConfig.harnessOptions} instead.
+     *
+     * Note: {@link HarnessOptions} is SLIMMED relative to this type — it omits
+     * `sessionStore`, `sessionPersistence`, `sessionTtl`, and `sessionPath` (those are
+     * now harness-adapter internals; see `src/types/providers.ts` → `ProviderOptions`
+     * @deprecated note). Migrating callers that relied on session-persistence config
+     * must move it to the concrete harness adapter.
+     *
+     * The v1.x provider-options merge cascade is superseded by the PRD §7.7 **harness**
+     * cascade (GlobalHarnessConfig.defaultHarness → AgentConfig.harness/harnessOptions →
+     * PromptOverrides.harness/harnessOptions), resolved via null-coalescing.
+     *
+     * ```typescript
+     * // BEFORE (v1.x)
+     * const config: AgentConfig = {
+     *   providerOptions: { endpoint: 'https://api.example.com', sessionPersistence: 'file' },
+     * };
+     * // AFTER (v1.2)
+     * const config: AgentConfig = {
+     *   harnessOptions: { endpoint: 'https://api.example.com', apiKey: process.env.ANTHROPIC_API_KEY },
+     * };
+     * ```
+     */
+    providerOptions?: ProviderOptions;
 }
 /**
  * Overrides that can be applied at the prompt level
@@ -62,5 +162,1156 @@ export interface PromptOverrides {
     enableReflection?: boolean;
     /** Override model for this prompt */
     model?: string;
+    /** Override harness for this prompt (PRD §7.7, §7.9). Highest priority in the harness cascade. */
+    harness?: HarnessId;
+    /** Override harness options for this prompt (PRD §7.7). Merged via last-write-wins. */
+    harnessOptions?: HarnessOptions;
+    /**
+     * Override provider for this prompt
+     *
+     * @deprecated Since v1.2. Use {@link PromptOverrides.harness} (and
+     *   {@link PromptOverrides.harnessOptions} for options) instead. The runtime/harness
+     *   axis (`'pi'` | `'claude-code'`) is now independent of the LLM provider/model
+     *   (PRD §7): the harness is chosen separately, and the model string is never
+     *   harness-qualified. This field is the highest-priority node in the PRD §7.7
+     *   **harness** cascade (GlobalHarnessConfig.defaultHarness → AgentConfig.harness →
+     *   PromptOverrides.harness). Retained for backward compatibility during the v1.2
+     *   migration; the Agent runtime reads it in lockstep with `harness`
+     *   (`overrides?.harness ?? overrides?.provider` in src/core/agent.ts).
+     *
+     * ```typescript
+     * // BEFORE (v1.x)
+     * const response = await agent.prompt(myPrompt, { provider: 'anthropic' });
+     * // AFTER (v1.2)
+     * const response = await agent.prompt(myPrompt, {
+     *   harness: 'claude-code',
+     *   model: 'anthropic/claude-sonnet-4-20250514',
+     * });
+     * ```
+     */
+    provider?: ProviderId;
+    /**
+     * Override provider options for this prompt
+     *
+     * @deprecated Since v1.2. Use {@link PromptOverrides.harnessOptions} instead.
+     *
+     * Note: {@link HarnessOptions} is SLIMMED relative to this type — it omits
+     * `sessionStore`, `sessionPersistence`, `sessionTtl`, and `sessionPath` (those are
+     * now harness-adapter internals; see `src/types/providers.ts` → `ProviderOptions`
+     * @deprecated note). Migrating callers that relied on session-persistence config
+     * must move it to the concrete harness adapter.
+     *
+     * The v1.x provider-options merge cascade is superseded by the PRD §7.7 **harness**
+     * cascade (GlobalHarnessConfig.defaultHarness → AgentConfig.harness/harnessOptions →
+     * PromptOverrides.harness/harnessOptions), resolved via null-coalescing.
+     *
+     * ```typescript
+     * // BEFORE (v1.x)
+     * const response = await agent.prompt(myPrompt, {
+     *   providerOptions: { endpoint: 'https://api.example.com', sessionPersistence: 'file' },
+     * });
+     * // AFTER (v1.2)
+     * const response = await agent.prompt(myPrompt, {
+     *   harnessOptions: { endpoint: 'https://api.example.com', apiKey: process.env.ANTHROPIC_API_KEY },
+     * });
+     * ```
+     */
+    providerOptions?: ProviderOptions;
 }
+/**
+ * Status of an agent response
+ * Used as discriminant for type narrowing
+ */
+export type AgentResponseStatus = 'success' | 'error' | 'partial';
+/**
+ * Response wrapper for agent execution results (discriminated union)
+ *
+ * ## PRD 6.4 Response Requirements
+ *
+ * All AgentResponse instances MUST satisfy:
+ *
+ * 1. **Strict JSON** (PRD 6.4.1): Must be parseable by `JSON.parse()`
+ * 2. **No Prose Wrapping** (PRD 6.4.2): No markdown code blocks or text
+ * 3. **Consistent Structure** (PRD 6.4.3): Must conform to this interface
+ * 4. **Null over Undefined** (PRD 6.4.4): Use `null` for absent values
+ * 5. **Error Responses** (PRD 6.4.5): Failed operations return valid JSON
+ *
+ * ## Discriminated Union Type Safety
+ *
+ * **This is a discriminated union type** - the `status` field determines the
+ * shape of `data` and `error` at compile-time. TypeScript will prevent invalid
+ * combinations like `status='success'` with `error!=null`.
+ *
+ * The three variants are:
+ * - **Success**: `status: 'success'`, `data: T`, `error: null`
+ * - **Error**: `status: 'error'`, `data: null`, `error: AgentErrorDetails`
+ * - **Partial**: `status: 'partial'`, `data: T`, `error: null`
+ *
+ * ## Type Narrowing
+ *
+ * Use the `status` field directly or type guards for type narrowing:
+ * - `isSuccess(response)` → `SuccessResponse<T>` (data is T, error is null)
+ * - `isError(response)` → `ErrorResponse` (data is null, error exists)
+ * - `isPartial(response)` → `PartialResponse<T>` (data is T, error is null)
+ *
+ * @template T - The type of data returned on success (unknown by default)
+ * @see {@link SuccessResponse}, {@link ErrorResponse}, {@link PartialResponse}
+ *
+ * @example <caption>Success response (PRD 6.5)</caption>
+ * ```ts
+ * const response: AgentResponse<{ result: string; artifacts: string[] }> = {
+ *   status: 'success',
+ *   data: { result: 'Task completed', artifacts: ['file1.ts', 'file2.ts'] },
+ *   error: null,  // Must be null for success - enforced by TypeScript
+ *   metadata: { agentId: 'agent-abc123', timestamp: 1706140800000, duration: 1523 }
+ * };
+ * ```
+ *
+ * @example <caption>Type narrowing with status field</caption>
+ * ```ts
+ * function handleResponse<T>(response: AgentResponse<T>) {
+ *   switch (response.status) {
+ *     case 'success':
+ *       // TypeScript knows: response.data is T, response.error is null
+ *       return response.data;
+ *     case 'error':
+ *       // TypeScript knows: response.data is null, response.error is AgentErrorDetails
+ *       throw new Error(response.error.message);
+ *     case 'partial':
+ *       // TypeScript knows: response.data is T, response.error is null
+ *       return response.data;
+ *     default:
+ *       // Exhaustiveness check - unreachable
+ *       const _exhaustive: never = response;
+ *       return _exhaustive;
+ *   }
+ * }
+ * ```
+ *
+ * @example <caption>Invalid combinations are compile-time errors</caption>
+ * ```ts
+ * // ❌ TYPE ERROR: status='success' with error!=null
+ * const invalid1: AgentResponse<string> = {
+ *   status: 'success',
+ *   data: 'hello',
+ *   error: { code: 'ERROR', message: 'oops', recoverable: false },  // Type error!
+ *   metadata: { agentId: 'test', timestamp: Date.now() }
+ * };
+ * // TypeScript error: Type '{ code: string; message: string; recoverable: boolean; }' is not assignable to type 'null'.
+ *
+ * // ❌ TYPE ERROR: status='error' with data!=null
+ * const invalid2: AgentResponse<string> = {
+ *   status: 'error',
+ *   data: 'hello',  // Type error!
+ *   error: { code: 'ERROR', message: 'oops', recoverable: false },
+ *   metadata: { agentId: 'test', timestamp: Date.now() }
+ * };
+ * // TypeScript error: Type 'string' is not assignable to type 'null'.
+ * ```
+ */
+export type AgentResponse<T = unknown> = {
+    status: 'success';
+    data: T;
+    error: null;
+    metadata: AgentResponseMetadata;
+} | {
+    status: 'error';
+    data: null;
+    error: AgentErrorDetails;
+    metadata: AgentResponseMetadata;
+} | {
+    status: 'partial';
+    data: T;
+    error: null;
+    metadata: AgentResponseMetadata;
+};
+/**
+ * Error details for agent error responses
+ *
+ * Per PRD 6.2: Error responses include machine-readable codes,
+ * human-readable messages, and a recoverable flag for retry logic.
+ *
+ * The `code` field uses SCREAMING_SNAKE_CASE convention and should
+ * be one of the standard codes from {@link AGENT_ERROR_CODES}.
+ *
+ * @see {@link AGENT_ERROR_CODES} for standard error codes
+ * @see {@link createErrorResponse} for factory function
+ *
+ * @example <caption>Error response (PRD 6.5)</caption>
+ * ```ts
+ * const error: AgentErrorDetails = {
+ *   code: 'EXECUTION_FAILED',
+ *   message: 'Failed to compile TypeScript files',
+ *   details: {
+ *     failedFiles: ['src/index.ts'],
+ *     compilerErrors: ['TS2307: Cannot find module \\'foo\\'']
+ *   },
+ *   recoverable: true
+ * };
+ * ```
+ */
+export interface AgentErrorDetails {
+    /**
+     * Machine-readable error code (SCREAMING_SNAKE_CASE convention)
+     *
+     * Use standard codes from {@link AGENT_ERROR_CODES} when applicable.
+     * Custom codes should follow the same naming convention.
+     */
+    code: string;
+    /** Human-readable error description suitable for display or logging */
+    message: string;
+    /**
+     * Additional error context - null if no details available
+     *
+     * May include field names, values, stack traces, or other diagnostic info.
+     * Per PRD 6.4.4: Use null instead of undefined for absent values.
+     */
+    details?: Record<string, unknown> | null;
+    /**
+     * Whether the error is recoverable (can retry)
+     *
+     * Set to true for transient errors (rate limits, network issues).
+     * Set to false for permanent errors (validation, invalid format).
+     *
+     * Per PRD 6.2: This is a hint for parent workflow retry logic.
+     */
+    recoverable: boolean;
+}
+/**
+ * Metadata for agent responses
+ *
+ * Per PRD 6.3: Response metadata includes agent identification,
+ * timing information, and optional correlation/tracing data.
+ *
+ * The timestamp is a Unix timestamp in milliseconds (not seconds).
+ * Use Date.now() or similar to generate valid timestamps.
+ *
+ * @see {@link TokenUsage} for token usage structure
+ *
+ * @example <caption>Metadata from PRD 6.5</caption>
+ * ```ts
+ * const metadata: AgentResponseMetadata = {
+ *   agentId: 'agent-abc123',
+ *   timestamp: 1706140800000,
+ *   duration: 1523
+ * };
+ * ```
+ *
+ * @example <caption>Full metadata with optional fields</caption>
+ * ```ts
+ * const metadata: AgentResponseMetadata = {
+ *   agentId: 'agent-abc123',
+ *   timestamp: Date.now(),
+ *   duration: 1523,
+ *   requestId: 'req-abc123',
+ *   usage: { inputTokens: 100, outputTokens: 50, cacheReadTokens: 0, cacheWriteTokens: 25 },
+ *   toolCalls: 3
+ * };
+ * ```
+ */
+export interface AgentResponseMetadata {
+    /**
+     * Agent identifier (required)
+     *
+     * Uniquely identifies the agent or workflow that generated this response.
+     * Should be stable across multiple invocations of the same agent.
+     */
+    agentId: string;
+    /**
+     * Unix timestamp in milliseconds (required)
+     *
+     * The time when the response was generated, as a Unix timestamp in
+     * milliseconds since the epoch (January 1, 1970). Use Date.now() to
+     * generate current timestamps.
+     *
+     * @example
+     * ```ts
+     * timestamp: Date.now()  // Current time in milliseconds
+     * timestamp: 1706140800000  // Fixed timestamp
+     * ```
+     */
+    timestamp: number;
+    /**
+     * Execution duration in milliseconds (optional)
+     *
+     * The time taken to execute the agent prompt, from start to completion.
+     * Useful for performance monitoring and debugging.
+     */
+    duration?: number | null;
+    /**
+     * Request correlation ID (optional)
+     *
+     * Used for tracing requests across distributed systems. Correlates
+     * this response with the original request and any downstream calls.
+     */
+    requestId?: string | null;
+    /**
+     * Token usage from the API (optional, for backward compatibility)
+     *
+     * Breakdown of token usage including input, output, and cache tokens.
+     * Only present when the API returns token usage information.
+     */
+    usage?: TokenUsage;
+    /**
+     * Number of tool invocations (optional, for backward compatibility)
+     *
+     * The count of tool/function calls made during agent execution.
+     * Useful for tracking agent behavior and cost analysis.
+     */
+    toolCalls?: number;
+}
+/**
+ * Success response type - data is T (not null), error is null
+ *
+ * Use this type with type guards for type-safe access to response data.
+ * When a response has status 'success', data is guaranteed to be T (not null).
+ *
+ * Per PRD 6.4.3: Consistent Structure - all success responses conform
+ * to the AgentResponse interface with status 'success'.
+ *
+ * @template T - The type of data returned on success
+ * @see {@link isSuccess} for the type guard that narrows to this type
+ *
+ * @example
+ * ```ts
+ * // Type narrowing with type guard
+ * if (isSuccess(response)) {
+ *   console.log(response.data); // TypeScript knows data is T
+ *   console.log(response.error); // TypeScript knows error is null
+ * }
+ * ```
+ */
+export type SuccessResponse<T> = AgentResponse<T> & {
+    status: 'success';
+};
+/**
+ * Error response type - data is null, error is AgentErrorDetails (not null)
+ *
+ * Use this type with type guards for type-safe access to error details.
+ * When a response has status 'error', error is guaranteed to be AgentErrorDetails (not null).
+ *
+ * Per PRD 6.4.5: Error Responses - failed operations must still return
+ * valid JSON with status 'error' and populated error field.
+ *
+ * @see {@link isError} for the type guard that narrows to this type
+ * @see {@link AgentErrorDetails} for error details structure
+ *
+ * @example
+ * ```ts
+ * // Type narrowing with type guard
+ * if (isError(response)) {
+ *   console.log(response.error.code); // TypeScript knows error exists
+ *   console.log(response.data); // TypeScript knows data is null
+ * }
+ * ```
+ */
+export type ErrorResponse = AgentResponse<null> & {
+    status: 'error';
+};
+/**
+ * Partial response type - data is T, error is null
+ *
+ * Used for streaming or incremental results where the agent has not
+ * yet completed the full request. Partial responses contain intermediate
+ * progress data that may be updated in subsequent responses.
+ *
+ * Per PRD 6.4.3: Consistent Structure - all partial responses conform
+ * to the AgentResponse interface with status 'partial'.
+ *
+ * @template T - The type of partial data returned
+ * @see {@link isPartial} for the type guard that narrows to this type
+ *
+ * @example
+ * ```ts
+ * // Type narrowing with type guard
+ * if (isPartial(response)) {
+ *   console.log('Progress:', response.data.completedSteps);
+ *   // TypeScript knows data is T and error is null
+ * }
+ * ```
+ */
+export type PartialResponse<T> = AgentResponse<T> & {
+    status: 'partial';
+};
+/**
+ * Standard error codes for agent responses
+ *
+ * All error codes use SCREAMING_SNAKE_CASE convention.
+ *
+ * Per PRD 6.6: Use `INVALID_RESPONSE_FORMAT` for responses that
+ * don't conform to the AgentResponse schema. Validation failures
+ * should be treated as errors with this code.
+ *
+ * @see {@link AgentErrorDetails} for error details structure
+ * @see {@link createErrorResponse} for factory function
+ *
+ * @example
+ * ```ts
+ * import { AGENT_ERROR_CODES, createErrorResponse } from 'groundswell';
+ *
+ * const error = createErrorResponse(
+ *   AGENT_ERROR_CODES.VALIDATION_FAILED,
+ *   'Invalid input',
+ *   { field: 'email', value: 'not-an-email' }
+ * );
+ * ```
+ */
+export declare const AGENT_ERROR_CODES: {
+    /**
+     * Response not valid JSON or doesn't match AgentResponse schema
+     *
+     * Per PRD 6.6: Invalid responses must be treated as errors with this code.
+     * Use when response validation fails during parsing or schema checking.
+     */
+    readonly INVALID_RESPONSE_FORMAT: "INVALID_RESPONSE_FORMAT";
+    /**
+     * Input validation failed
+     *
+     * Use when the provided inputs fail validation checks (e.g., wrong type,
+     * missing required fields, out-of-range values).
+     */
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    /**
+     * Agent execution failed
+     *
+     * Use when the agent execution fails for reasons unrelated to validation
+     * or API requests (e.g., compilation errors, runtime exceptions).
+     */
+    readonly EXECUTION_FAILED: "EXECUTION_FAILED";
+    /**
+     * API request to LLM provider failed
+     *
+     * Use when the HTTP request to the LLM provider fails (e.g., network errors,
+     * timeout, rate limiting, provider-side errors).
+     */
+    readonly API_REQUEST_FAILED: "API_REQUEST_FAILED";
+    /**
+     * Tool execution failed
+     *
+     * Use when a tool/function invocation fails during agent execution
+     * (e.g., tool not found, tool returned error, tool timeout).
+     */
+    readonly TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED";
+    /**
+     * Internal validation or system error
+     *
+     * Use when an internal validation fails or a system error occurs.
+     * This indicates a bug in the code (e.g., factory helper produced invalid response).
+     * Non-recoverable because retrying with the same inputs will produce the same error.
+     *
+     * Per PRD 6.6: Internal validation failures should return this error code.
+     */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    /**
+     * Invalid harness/provider configuration
+     *
+     * Use when a harness receives a configuration it cannot honour — e.g. a model
+     * provider it cannot run (ClaudeCodeHarness only runs anthropic/* per PRD §7.8).
+     * Non-recoverable: the caller must select a different harness or model, not retry.
+     */
+    readonly CONFIG_ERROR: "CONFIG_ERROR";
+};
+/**
+ * Creates a success response with data and metadata.
+ *
+ * ## PRD 6.4 Compliance
+ *
+ * The returned response satisfies all PRD 6.4 requirements:
+ * - Strict JSON parseable by `JSON.parse()` (PRD 6.4.1)
+ * - No prose wrapping - pure JSON structure (PRD 6.4.2)
+ * - Consistent with AgentResponse interface (PRD 6.4.3)
+ * - Uses null instead of undefined (PRD 6.4.4)
+ *
+ * @template T - The type of the response data
+ * @param data - The response data to return
+ * @param metadata - Response metadata including agentId and timestamp
+ * @returns A success AgentResponse with status 'success', provided data, null error
+ *
+ * @example <caption>Basic success response (PRD 6.5)</caption>
+ * ```ts
+ * const response = createSuccessResponse(
+ *   { result: 'Task completed', artifacts: ['file1.ts', 'file2.ts'] },
+ *   { agentId: 'agent-abc123', timestamp: 1706140800000, duration: 1523 }
+ * );
+ *
+ * // Guaranteed to be valid JSON (PRD 6.4.1)
+ * const jsonString = JSON.stringify(response);
+ * const parsed = JSON.parse(jsonString); // Always valid
+ * ```
+ *
+ * @example <caption>Success response with execution metadata</caption>
+ * ```ts
+ * const response = createSuccessResponse(
+ *   { items: [1, 2, 3] },
+ *   {
+ *     agentId: 'agent-123',
+ *     timestamp: Date.now(),
+ *     duration: 1523,
+ *     requestId: 'req-abc123'
+ *   }
+ * );
+ * ```
+ */
+export declare function createSuccessResponse<T>(data: T, metadata: AgentResponseMetadata): AgentResponse<T>;
+/**
+ * Creates an error response with error details.
+ *
+ * ## PRD 6.4 Compliance
+ *
+ * Per PRD 6.4.5: Failed operations must still return valid JSON with
+ * status 'error' and populated error field. This function ensures all
+ * error responses conform to the AgentResponse schema.
+ *
+ * The error code should use SCREAMING_SNAKE_CASE convention and ideally
+ * be one of the standard codes from {@link AGENT_ERROR_CODES}.
+ *
+ * @param code - Machine-readable error code (SCREAMING_SNAKE_CASE)
+ * @param message - Human-readable error message
+ * @param details - Optional additional error context (use null instead of undefined per PRD 6.4.4)
+ * @param recoverable - Whether the error is recoverable (default: false)
+ * @returns An error AgentResponse with null data, populated error field
+ *
+ * @example <caption>Error response (PRD 6.5)</caption>
+ * ```ts
+ * const response = createErrorResponse(
+ *   'EXECUTION_FAILED',
+ *   'Failed to compile TypeScript files',
+ *   {
+ *     failedFiles: ['src/index.ts'],
+ *     compilerErrors: ['TS2307: Cannot find module \\'foo\\'']
+ *   },
+ *   true
+ * );
+ * ```
+ *
+ * @example <caption>Using standard error codes</caption>
+ * ```ts
+ * import { AGENT_ERROR_CODES, createErrorResponse } from 'groundswell';
+ *
+ * const response = createErrorResponse(
+ *   AGENT_ERROR_CODES.VALIDATION_FAILED,
+ *   'Invalid input',
+ *   { field: 'email', value: 'not-an-email' },
+ *   false
+ * );
+ * ```
+ */
+export declare function createErrorResponse(code: string, message: string, details?: Record<string, unknown>, recoverable?: boolean): AgentResponse<null>;
+/**
+ * Creates a partial response for streaming/incremental results.
+ *
+ * ## PRD 6.4 Compliance
+ *
+ * Per PRD 6.4.3: Consistent Structure - partial responses conform to
+ * the AgentResponse interface with status 'partial'.
+ *
+ * Partial responses are used for streaming or incremental results where
+ * the agent has not yet completed the full request. They contain intermediate
+ * progress data that may be updated in subsequent responses.
+ *
+ * @template T - The type of the partial response data
+ * @param data - The partial response data with progress information
+ * @returns A partial AgentResponse with status 'partial', data, null error
+ *
+ * @example <caption>Partial response (PRD 6.5)</caption>
+ * ```ts
+ * const response = createPartialResponse({
+ *   completedSteps: 3,
+ *   totalSteps: 5,
+ *   intermediateResult: { progress: 'processing file2.ts' }
+ * });
+ *
+ * // Later, send another partial response with updated progress
+ * const updatedResponse = createPartialResponse({
+ *   completedSteps: 4,
+ *   totalSteps: 5,
+ *   intermediateResult: { progress: 'processing file3.ts' }
+ * });
+ * ```
+ *
+ * @example <caption>Streaming data chunks</caption>
+ * ```ts
+ * const chunk = createPartialResponse({
+ *   chunk: 'Hello',
+ *   isComplete: false
+ * });
+ * ```
+ */
+export declare function createPartialResponse<T>(data: T): AgentResponse<T>;
+/**
+ * Type guard for success responses.
+ * Narrows the type to SuccessResponse<T> where data is T (not null).
+ *
+ * @param response - The response to check
+ * @returns True if the response status is 'success'
+ *
+ * @example
+ * ```ts
+ * if (isSuccess(response)) {
+ *   console.log(response.data); // TypeScript knows data is T
+ * }
+ * ```
+ */
+export declare function isSuccess<T>(response: AgentResponse<T>): response is SuccessResponse<T>;
+/**
+ * Type guard for error responses.
+ * Narrows the type to ErrorResponse where error is AgentErrorDetails (not null).
+ *
+ * @param response - The response to check
+ * @returns True if the response status is 'error'
+ *
+ * @example
+ * ```ts
+ * if (isError(response)) {
+ *   console.log(response.error.code); // TypeScript knows error exists
+ * }
+ * ```
+ */
+export declare function isError<T>(response: AgentResponse<T>): response is ErrorResponse;
+/**
+ * Type guard for partial responses.
+ * Narrows the type to PartialResponse<T>.
+ *
+ * @param response - The response to check
+ * @returns True if the response status is 'partial'
+ *
+ * @example
+ * ```ts
+ * if (isPartial(response)) {
+ *   console.log('Partial result:', response.data);
+ * }
+ * ```
+ */
+export declare function isPartial<T>(response: AgentResponse<T>): response is PartialResponse<T>;
+/**
+ * Zod schema for AgentResponseStatus enum
+ * Validates status values: 'success' | 'error' | 'partial'
+ *
+ * @example
+ * ```ts
+ * AgentResponseStatusSchema.parse('success'); // ✓
+ * AgentResponseStatusSchema.parse('invalid'); // ✗ ZodError
+ * ```
+ */
+export declare const AgentResponseStatusSchema: z.ZodEnum<["success", "error", "partial"]>;
+/**
+ * Zod schema for AgentErrorDetails interface
+ * Validates error details with null-over-undefined handling
+ *
+ * Per PRD 6.4.4: Use null for absent values, not undefined
+ */
+export declare const AgentErrorDetailsSchema: z.ZodObject<{
+    /** Machine-readable error code (SCREAMING_SNAKE_CASE) */
+    code: z.ZodString;
+    /** Human-readable error description */
+    message: z.ZodString;
+    /** Additional error context - null if no details (PRD 6.4.4) */
+    details: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Whether the error is recoverable (can retry) */
+    recoverable: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    details: Record<string, unknown> | null;
+    recoverable: boolean;
+}, {
+    code: string;
+    message: string;
+    details: Record<string, unknown> | null;
+    recoverable: boolean;
+}>;
+/**
+ * Zod schema for AgentResponseMetadata interface
+ * Validates response metadata including agent ID and timestamp
+ */
+export declare const AgentResponseMetadataSchema: z.ZodObject<{
+    /** Agent identifier */
+    agentId: z.ZodString;
+    /** Unix timestamp in milliseconds */
+    timestamp: z.ZodNumber;
+    /** Execution duration in milliseconds (optional) */
+    duration: z.ZodOptional<z.ZodNumber>;
+    /** Request correlation ID (optional) */
+    requestId: z.ZodOptional<z.ZodString>;
+    /** Token usage from API (optional - passthrough for complex type) */
+    usage: z.ZodOptional<z.ZodUnknown>;
+    /** Number of tool invocations (optional) */
+    toolCalls: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    agentId: string;
+    timestamp: number;
+    usage?: unknown;
+    duration?: number | undefined;
+    requestId?: string | undefined;
+    toolCalls?: number | undefined;
+}, {
+    agentId: string;
+    timestamp: number;
+    usage?: unknown;
+    duration?: number | undefined;
+    requestId?: string | undefined;
+    toolCalls?: number | undefined;
+}>;
+/**
+ * Zod schema factory for AgentResponse<T> discriminated union
+ * Creates a schema that validates responses based on status discriminator
+ *
+ * @template T - The Zod schema for the data type
+ * @param dataSchema - Zod schema for the response data
+ * @returns A discriminated union schema for AgentResponse
+ *
+ * @example
+ * ```ts
+ * // Create schema for string responses
+ * const StringResponseSchema = AgentResponseSchema(z.object({ result: z.string() }));
+ *
+ * // Validate a success response
+ * const result = StringResponseSchema.safeParse({
+ *   status: 'success',
+ *   data: { result: 'hello' },
+ *   error: null,
+ *   metadata: { agentId: 'test', timestamp: Date.now() }
+ * });
+ * ```
+ */
+export declare function AgentResponseSchema<T extends z.ZodTypeAny>(dataSchema: T): z.ZodEffects<z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
+    status: z.ZodLiteral<"success">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    status: z.ZodLiteral<"success">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, z.baseObjectInputType<{
+    status: z.ZodLiteral<"success">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}> extends infer T_2 ? { [k_1 in keyof T_2]: T_2[k_1]; } : never>, z.ZodObject<{
+    status: z.ZodLiteral<"error">;
+    data: z.ZodNull;
+    error: z.ZodObject<{
+        /** Machine-readable error code (SCREAMING_SNAKE_CASE) */
+        code: z.ZodString;
+        /** Human-readable error description */
+        message: z.ZodString;
+        /** Additional error context - null if no details (PRD 6.4.4) */
+        details: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /** Whether the error is recoverable (can retry) */
+        recoverable: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        details: Record<string, unknown> | null;
+        recoverable: boolean;
+    }, {
+        code: string;
+        message: string;
+        details: Record<string, unknown> | null;
+        recoverable: boolean;
+    }>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown> | null;
+        recoverable: boolean;
+    };
+    status: "error";
+    data: null;
+    metadata?: {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    } | undefined;
+}, {
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown> | null;
+        recoverable: boolean;
+    };
+    status: "error";
+    data: null;
+    metadata?: {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    } | undefined;
+}>, z.ZodObject<{
+    status: z.ZodLiteral<"partial">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    status: z.ZodLiteral<"partial">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}>, any> extends infer T_3 ? { [k_2 in keyof T_3]: T_3[k_2]; } : never, z.baseObjectInputType<{
+    status: z.ZodLiteral<"partial">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}> extends infer T_4 ? { [k_3 in keyof T_4]: T_4[k_3]; } : never>]>, (z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    status: z.ZodLiteral<"success">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}>, any> extends infer T_5 ? { [k in keyof T_5]: T_5[k]; } : never) | {
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown> | null;
+        recoverable: boolean;
+    };
+    status: "error";
+    data: null;
+    metadata?: {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    } | undefined;
+} | (z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    status: z.ZodLiteral<"partial">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}>, any> extends infer T_6 ? { [k_2 in keyof T_6]: T_6[k_2]; } : never), (z.baseObjectInputType<{
+    status: z.ZodLiteral<"success">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}> extends infer T_7 ? { [k_1 in keyof T_7]: T_7[k_1]; } : never) | {
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown> | null;
+        recoverable: boolean;
+    };
+    status: "error";
+    data: null;
+    metadata?: {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    } | undefined;
+} | (z.baseObjectInputType<{
+    status: z.ZodLiteral<"partial">;
+    data: T;
+    error: z.ZodNull;
+    metadata: z.ZodOptional<z.ZodObject<{
+        /** Agent identifier */
+        agentId: z.ZodString;
+        /** Unix timestamp in milliseconds */
+        timestamp: z.ZodNumber;
+        /** Execution duration in milliseconds (optional) */
+        duration: z.ZodOptional<z.ZodNumber>;
+        /** Request correlation ID (optional) */
+        requestId: z.ZodOptional<z.ZodString>;
+        /** Token usage from API (optional - passthrough for complex type) */
+        usage: z.ZodOptional<z.ZodUnknown>;
+        /** Number of tool invocations (optional) */
+        toolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }, {
+        agentId: string;
+        timestamp: number;
+        usage?: unknown;
+        duration?: number | undefined;
+        requestId?: string | undefined;
+        toolCalls?: number | undefined;
+    }>>;
+}> extends infer T_8 ? { [k_3 in keyof T_8]: T_8[k_3]; } : never)>;
 //# sourceMappingURL=agent.d.ts.map