groundswell 0.0.3 → 1.0.0

package/dist/utils/agent-validation.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Agent response validation utilities
+ *
+ * Provides pure, side-effect-free functions for validating AgentResponse
+ * instances using Zod schemas. The utilities enable both Agent and Workflow
+ * classes to perform validation without duplicating code.
+ *
+ * @module agent-validation
+ */
+import type { AgentResponse } from '../types/agent.js';
+import { z } from 'zod';
+/**
+ * Validation result type for agent response validation
+ *
+ * Provides structured validation result with boolean validity flag
+ * and optional ZodError for detailed error information.
+ */
+export interface ValidationResult {
+    /** Whether the response is valid according to the schema */
+    valid: boolean;
+    /** Zod validation errors (present when valid is false) */
+    errors?: z.ZodError;
+}
+/**
+ * Validate an AgentResponse against a Zod schema
+ *
+ * This is a pure, side-effect-free function that validates AgentResponse
+ * instances using Zod schemas. It returns a structured ValidationResult
+ * with validity flag and optional error details.
+ *
+ * **Validation Flow:**
+ * 1. Create AgentResponseSchema using provided dataSchema
+ * 2. Call schema.safeParse(response) for non-throwing validation
+ * 3. Return { valid: true } if validation succeeds
+ * 4. Return { valid: false, errors: ZodError } if validation fails
+ *
+ * **Pure Function Guarantee:**
+ * - Deterministic: Same input always produces same output
+ * - No side effects: Doesn't modify inputs, emit events, or log
+ * - No external dependencies: Doesn't use Date.now(), Math.random(), etc.
+ *
+ * @template T - The type of response data
+ * @param response - The AgentResponse to validate
+ * @param dataSchema - The Zod schema for the response data (defaults to z.unknown())
+ * @returns Structured validation result with validity flag and optional errors
+ *
+ * @example Valid response
+ * ```ts
+ * const response: AgentResponse<string> = {
+ *   status: 'success',
+ *   data: 'Hello, World!',
+ *   error: null,
+ *   metadata: { agentId: 'agent-123', timestamp: Date.now() }
+ * };
+ *
+ * const result = validateAgentResponse(response);
+ * // Returns: { valid: true }
+ * ```
+ *
+ * @example Invalid response
+ * ```ts
+ * const response = {
+ *   status: 'success',
+ *   data: null,  // Invalid: data should be string, not null
+ *   error: null,
+ *   metadata: { agentId: 'agent-123', timestamp: Date.now() }
+ * };
+ *
+ * const result = validateAgentResponse(response, z.string());
+ * // Returns: { valid: false, errors: ZodError }
+ * ```
+ *
+ * @remarks
+ * **Integration with Agent.validateResponse():**
+ * This utility is called by Agent.validateResponse() which adds:
+ * - console.error logging with agentId
+ * - INTERNAL_ERROR response creation on validation failure
+ *
+ * **Integration with Workflow.validateAgentResponse():**
+ * This utility is called by Workflow.validateAgentResponse() which adds:
+ * - invalidResponse event emission
+ * - WorkflowError creation with INVALID_RESPONSE_FORMAT context
+ *
+ * @see {@link AgentResponseSchema} - Schema factory used for validation
+ * @see {@link ValidationResult} - Return type structure
+ */
+export declare function validateAgentResponse<T>(response: AgentResponse<T>, dataSchema?: z.ZodTypeAny): ValidationResult;
+//# sourceMappingURL=agent-validation.d.ts.map

package/dist/utils/agent-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-validation.d.ts","sourceRoot":"","sources":["../../src/utils/agent-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,KAAK,EAAE,OAAO,CAAC;IACf,0DAA0D;IAC1D,MAAM,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,UAAU,GAAE,CAAC,CAAC,UAAwB,GACrC,gBAAgB,CAclB"}

package/dist/utils/agent-validation.js

@@ -0,0 +1,87 @@
+/**
+ * Agent response validation utilities
+ *
+ * Provides pure, side-effect-free functions for validating AgentResponse
+ * instances using Zod schemas. The utilities enable both Agent and Workflow
+ * classes to perform validation without duplicating code.
+ *
+ * @module agent-validation
+ */
+import { AgentResponseSchema } from '../types/agent.js';
+import { z } from 'zod';
+/**
+ * Validate an AgentResponse against a Zod schema
+ *
+ * This is a pure, side-effect-free function that validates AgentResponse
+ * instances using Zod schemas. It returns a structured ValidationResult
+ * with validity flag and optional error details.
+ *
+ * **Validation Flow:**
+ * 1. Create AgentResponseSchema using provided dataSchema
+ * 2. Call schema.safeParse(response) for non-throwing validation
+ * 3. Return { valid: true } if validation succeeds
+ * 4. Return { valid: false, errors: ZodError } if validation fails
+ *
+ * **Pure Function Guarantee:**
+ * - Deterministic: Same input always produces same output
+ * - No side effects: Doesn't modify inputs, emit events, or log
+ * - No external dependencies: Doesn't use Date.now(), Math.random(), etc.
+ *
+ * @template T - The type of response data
+ * @param response - The AgentResponse to validate
+ * @param dataSchema - The Zod schema for the response data (defaults to z.unknown())
+ * @returns Structured validation result with validity flag and optional errors
+ *
+ * @example Valid response
+ * ```ts
+ * const response: AgentResponse<string> = {
+ *   status: 'success',
+ *   data: 'Hello, World!',
+ *   error: null,
+ *   metadata: { agentId: 'agent-123', timestamp: Date.now() }
+ * };
+ *
+ * const result = validateAgentResponse(response);
+ * // Returns: { valid: true }
+ * ```
+ *
+ * @example Invalid response
+ * ```ts
+ * const response = {
+ *   status: 'success',
+ *   data: null,  // Invalid: data should be string, not null
+ *   error: null,
+ *   metadata: { agentId: 'agent-123', timestamp: Date.now() }
+ * };
+ *
+ * const result = validateAgentResponse(response, z.string());
+ * // Returns: { valid: false, errors: ZodError }
+ * ```
+ *
+ * @remarks
+ * **Integration with Agent.validateResponse():**
+ * This utility is called by Agent.validateResponse() which adds:
+ * - console.error logging with agentId
+ * - INTERNAL_ERROR response creation on validation failure
+ *
+ * **Integration with Workflow.validateAgentResponse():**
+ * This utility is called by Workflow.validateAgentResponse() which adds:
+ * - invalidResponse event emission
+ * - WorkflowError creation with INVALID_RESPONSE_FORMAT context
+ *
+ * @see {@link AgentResponseSchema} - Schema factory used for validation
+ * @see {@link ValidationResult} - Return type structure
+ */
+export function validateAgentResponse(response, dataSchema = z.unknown()) {
+    // Create schema for this response type
+    const schema = AgentResponseSchema(dataSchema);
+    // Validate response against schema (non-throwing)
+    const validation = schema.safeParse(response);
+    if (validation.success) {
+        // Response is valid
+        return { valid: true };
+    }
+    // Validation failed - return structured error
+    return { valid: false, errors: validation.error };
+}
+//# sourceMappingURL=agent-validation.js.map

package/dist/utils/agent-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-validation.js","sourceRoot":"","sources":["../../src/utils/agent-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAA0B,EAC1B,aAA2B,CAAC,CAAC,OAAO,EAAE;IAEtC,uCAAuC;IACvC,MAAM,MAAM,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAE/C,kDAAkD;IAClD,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE9C,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;QACvB,oBAAoB;QACpB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,8CAA8C;IAC9C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC;AACpD,CAAC"}

package/dist/utils/delay.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Creates a promise that resolves after a specified delay
+ * @param ms - Delay in milliseconds
+ * @returns Promise that resolves after delay
+ */
+export declare function delay(ms: number): Promise<void>;
+//# sourceMappingURL=delay.d.ts.map

package/dist/utils/delay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../../src/utils/delay.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/utils/delay.js

@@ -0,0 +1,9 @@
+/**
+ * Creates a promise that resolves after a specified delay
+ * @param ms - Delay in milliseconds
+ * @returns Promise that resolves after delay
+ */
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=delay.js.map

package/dist/utils/delay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay.js","sourceRoot":"","sources":["../../src/utils/delay.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/utils/harness-config.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Harness configuration cascade utilities (PRD §7.6 / §7.7).
+ *
+ * ## Dual-Cascade Architecture
+ *
+ * This module provides the v1.2 canonical harness-configuration functions that operate
+ * on the `GlobalHarnessConfig` / `HarnessId` / `HarnessOptions` types. It also contains
+ * deprecated legacy aliases (`configureProviders` / `getGlobalProviderConfig` /
+ * `resolveProviderConfig` / `resetGlobalConfig`) that preserve backward compatibility
+ * with existing consumers (`agent.ts`, legacy test files) during the migration.
+ *
+ * ## Dual-Singleton Design (Scope Decision)
+ *
+ * The legacy and harness functions validate **disjoint id sets**:
+ *   - `configureHarnesses` accepts only `'pi' | 'claude-code'`
+ *   - `configureProviders` accepts the full `ProviderId` superset (including `'anthropic'`)
+ *
+ * Existing consumers (agent.ts, 4 integration/override test files) pass `'anthropic'`
+ * through `configureProviders`. Making it delegate to `configureHarnesses` would throw and break
+ * those consumers, which are out of scope for this task (owned by P3.M1 / P4.M1).
+ *
+ * Therefore, **`configureProviders` keeps its own module-private singleton** with permissive
+ * validation, while `resolveProviderConfig` safely delegates to `resolveHarnessConfig` (which
+ * performs NO id validation — it treats ids as opaque string keys).
+ *
+ * Once P3.M1 rewires agent.ts to read the harness path and P4.M1 removes the legacy literals,
+ * the legacy singleton can be deleted and the aliases collapse to true delegation.
+ *
+ * @see {@link GlobalHarnessConfig} in types/harnesses.ts
+ * @see {@link GlobalProviderConfig} in types/providers.ts
+ */
+import type { GlobalHarnessConfig, HarnessId, HarnessOptions } from '../types/harnesses.js';
+import type { GlobalProviderConfig, ProviderId, ProviderOptions } from '../types/providers.js';
+/**
+ * Configure the global harness settings.
+ *
+ * Validates and stores the harness configuration. Should be called once at
+ * application startup. The harness cascade (PRD §7.7) uses this as the lowest
+ * priority layer — agent and prompt overrides take precedence.
+ *
+ * ## Validation
+ *
+ * - `defaultHarness` must be `'pi'` or `'claude-code'`
+ * - `harnessDefaults` keys (if present) must be valid `HarnessId` values
+ * - `defaultModelProvider` is an **open set** (any string) — NOT validated (PRD §7.8)
+ *
+ * @param config - Global harness configuration
+ * @throws {Error} If `defaultHarness` is invalid
+ * @throws {Error} If `harnessDefaults` contains invalid harness IDs
+ *
+ * @example
+ * ```ts
+ * import { configureHarnesses } from 'groundswell';
+ *
+ * configureHarnesses({
+ *   defaultHarness: 'pi',
+ *   defaultModelProvider: 'anthropic',
+ *   harnessDefaults: {
+ *     'claude-code': { apiKey: process.env.ANTHROPIC_API_KEY },
+ *   },
+ * });
+ * ```
+ */
+export declare function configureHarnesses(config: GlobalHarnessConfig): void;
+/**
+ * Get the current global harness configuration.
+ *
+ * Returns the configured value if `configureHarnesses()` was called, otherwise
+ * returns the default configuration. **Never returns null.**
+ *
+ * @returns Current global harness configuration
+ *
+ * @example
+ * ```ts
+ * const config = getGlobalHarnessConfig();
+ * console.log(config.defaultHarness); // 'pi' (default)
+ * ```
+ */
+export declare function getGlobalHarnessConfig(): GlobalHarnessConfig;
+/**
+ * Resolve harness configuration via the PRD §7.7 cascade.
+ *
+ * A **pure function** — takes `globalConfig` as a parameter and does NOT read
+ * the singleton. This purity enables both `resolveHarnessConfig` and the legacy
+ * `resolveProviderConfig` (which delegates to this function) to work correctly.
+ *
+ * ## Provider Resolution (nullish coalescing — prompt wins)
+ *
+ * ```ts
+ * const harness = promptHarness ?? agentHarness ?? globalConfig.defaultHarness;
+ * ```
+ *
+ * ## Options Merge (object spread — last write wins)
+ *
+ * ```ts
+ * const options = {
+ *   ...globalConfig.harnessDefaults?.[harness],  // base
+ *   ...agentOptions,                                // middle
+ *   ...promptOptions,                               // top
+ * };
+ * ```
+ *
+ * @param globalConfig - Global harness configuration
+ * @param agentHarness - Agent-level harness override (optional)
+ * @param agentOptions - Agent-level options override (optional)
+ * @param promptHarness - Prompt-level harness override (optional)
+ * @param promptOptions - Prompt-level options override (optional)
+ * @returns Resolved harness and merged options
+ */
+export declare function resolveHarnessConfig(globalConfig: GlobalHarnessConfig, agentHarness?: HarnessId, agentOptions?: HarnessOptions, promptHarness?: HarnessId, promptOptions?: HarnessOptions): {
+    harness: HarnessId;
+    options: HarnessOptions;
+};
+/**
+ * Reset the global harness configuration to defaults.
+ *
+ * **FOR TESTING PURPOSES ONLY.**
+ *
+ * @internal
+ */
+export declare function resetGlobalHarnessConfig(): void;
+/**
+ * Configure global provider settings.
+ *
+ * @deprecated Since v1.2. Use {@link configureHarnesses}.
+ *
+ * This function keeps its **own module-private singleton** (`globalProviderConfig`)
+ * with permissive `ProviderId` validation. It does NOT delegate to
+ * `configureHarnesses` because the harness validator rejects `'anthropic'`,
+ * which existing consumers still pass.
+ *
+ * @param config - Global provider configuration
+ * @throws {Error} If `defaultProvider` is invalid
+ * @throws {Error} If `providerDefaults` contains invalid provider IDs
+ */
+export declare function configureProviders(config: GlobalProviderConfig): void;
+/**
+ * Get the current global provider configuration.
+ *
+ * @deprecated Since v1.2. Use {@link getGlobalHarnessConfig}.
+ *
+ * Reads the legacy `globalProviderConfig` singleton. Returns the configured value
+ * if `configureProviders()` was called, otherwise the legacy default
+ * (`defaultProvider: 'anthropic'`). **Never returns null.**
+ *
+ * @returns Current global provider configuration
+ */
+export declare function getGlobalProviderConfig(): GlobalProviderConfig;
+/**
+ * Resolve provider configuration via the cascade.
+ *
+ * @deprecated Since v1.2. Use {@link resolveHarnessConfig}.
+ *
+ * **Delegates to {@link resolveHarnessConfig}** — the cascade algorithm is shared.
+ * Translates the `GlobalProviderConfig` shape to `GlobalHarnessConfig` (field renames),
+ * calls `resolveHarnessConfig` (which performs NO id validation — safe for legacy literals),
+ * and maps the result back to `{ provider, options }`.
+ *
+ * @param globalConfig - Global provider configuration from configureProviders()
+ * @param agentProvider - Agent-level provider override (optional)
+ * @param agentOptions - Agent-level options override (optional)
+ * @param promptProvider - Prompt-level provider override (optional)
+ * @param promptOptions - Prompt-level options override (optional)
+ * @returns Resolved provider and merged options
+ */
+export declare function resolveProviderConfig(globalConfig: GlobalProviderConfig, agentProvider?: ProviderId, agentOptions?: ProviderOptions, promptProvider?: ProviderId, promptOptions?: ProviderOptions): {
+    provider: ProviderId;
+    options: ProviderOptions;
+};
+/**
+ * Reset global configuration to defaults.
+ *
+ * @deprecated Since v1.2. Use {@link resetGlobalHarnessConfig}.
+ *
+ * **FOR TESTING PURPOSES ONLY.**
+ *
+ * @internal
+ */
+export declare function resetGlobalConfig(): void;
+//# sourceMappingURL=harness-config.d.ts.map

package/dist/utils/harness-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-config.d.ts","sourceRoot":"","sources":["../../src/utils/harness-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,SAAS,EACT,cAAc,EACf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,eAAe,EAChB,MAAM,uBAAuB,CAAC;AA4C/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAuBpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI,mBAAmB,CAE5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,mBAAmB,EACjC,YAAY,CAAC,EAAE,SAAS,EACxB,YAAY,CAAC,EAAE,cAAc,EAC7B,aAAa,CAAC,EAAE,SAAS,EACzB,aAAa,CAAC,EAAE,cAAc,GAC7B;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAejD;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAiDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAuBrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CAE9D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,oBAAoB,EAClC,aAAa,CAAC,EAAE,UAAU,EAC1B,YAAY,CAAC,EAAE,eAAe,EAC9B,cAAc,CAAC,EAAE,UAAU,EAC3B,aAAa,CAAC,EAAE,eAAe,GAC9B;IAAE,QAAQ,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAmBpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}