groundswell 0.0.2 → 1.0.0

package/dist/utils/model-spec.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Model specification parsing utility
+ *
+ * Provides parsing and validation of model specification strings
+ * per PRD §7.8 (Model & Provider Specification).
+ *
+ * The provider axis is an OPEN set (PRD §7.8): any non-empty provider string
+ * is valid. The harness (pi | claude-code) is NEVER part of the model string —
+ * harness-qualified strings (e.g. `pi/anthropic/x`) are rejected.
+ */
+import type { ModelSpec, ModelProviderId } from '../types/harnesses.js';
+/**
+ * Parse a model specification string into a ModelSpec object
+ *
+ * ## Supported Formats
+ *
+ * ### Qualified Format (provider/model)
+ * Explicit provider specification with "/" separator.
+ * - Input: `"anthropic/claude-3-5-sonnet"`
+ * - Output: `{ provider: 'anthropic', model: 'claude-3-5-sonnet', raw: 'anthropic/claude-3-5-sonnet' }`
+ *
+ * ### Plain Format (model only)
+ * Uses default provider when no provider specified.
+ * - Input: `"claude-sonnet-4"` with defaultProvider: `'anthropic'`
+ * - Output: `{ provider: 'anthropic', model: 'claude-sonnet-4', raw: 'claude-sonnet-4' }`
+ *
+ * ## Validation Rules
+ *
+ * 1. Input cannot be empty or whitespace-only
+ * 2. Provider must be a non-empty string (open set — any LLM provider accepted)
+ * 3. Model name cannot be empty after provider split
+ * 4. Harness-qualified strings (3+ segments, e.g. `pi/anthropic/x`) are REJECTED
+ *    (PRD §7.8 critical rule: the harness must never appear in the model string)
+ * 5. Input is trimmed before parsing, original preserved in `raw` field
+ *
+ * @param model - Model specification string to parse
+ * @param defaultProvider - Default provider to use when none specified (default: 'anthropic')
+ * @returns Parsed ModelSpec object with provider, model, and raw string
+ * @throws {Error} When model specification is invalid:
+ * - Empty or whitespace-only input
+ * - Empty provider or model parts
+ * - Harness-qualified strings (3+ segments)
+ *
+ * @example
+ * ```ts
+ * // Qualified format with known provider
+ * const spec1 = parseModelSpec('anthropic/claude-3-5-sonnet');
+ * // Returns: { provider: 'anthropic', model: 'claude-3-5-sonnet', raw: 'anthropic/claude-3-5-sonnet' }
+ *
+ * // Qualified format with custom provider (open set)
+ * const spec2 = parseModelSpec('openai/gpt-4o');
+ * // Returns: { provider: 'openai', model: 'gpt-4o', raw: 'openai/gpt-4o' }
+ *
+ * // Plain format — resolved against default provider
+ * const spec3 = parseModelSpec('claude-sonnet-4');
+ * // Returns: { provider: 'anthropic', model: 'claude-sonnet-4', raw: 'claude-sonnet-4' }
+ *
+ * // Harness-qualified — REJECTED (PRD §7.8 critical rule)
+ * parseModelSpec('pi/anthropic/claude-sonnet-4');
+ * // Throws: "Harness must not appear in model string …"
+ * ```
+ *
+ * @see {@link ModelSpec} for the return type structure
+ * @see {@link ModelProviderId} for the open provider set
+ */
+export declare function parseModelSpec(model: string, defaultProvider?: ModelProviderId): ModelSpec;
+/**
+ * Format a ModelSpec for a specific target provider
+ *
+ * ## Behavior
+ *
+ * ### Same Provider (Pass-Through)
+ * When `spec.provider` matches `targetProvider`, returns the model name only.
+ *
+ * **Example:**
+ * - Input: `{ provider: 'anthropic', model: 'claude-3-5-sonnet', raw: 'anthropic/claude-3-5-sonnet' }`, `'anthropic'`
+ * - Output: `"claude-3-5-sonnet"`
+ *
+ * ### Different Providers (Error)
+ * When providers differ, throws an error. Cross-provider model translation
+ * is not supported in the MVP.
+ *
+ * @param spec - ModelSpec from parseModelSpec() or Provider.normalizeModel()
+ * @param targetProvider - The provider to format the model for
+ * @returns Formatted model string for target provider (model name only)
+ * @throws {Error} When providers differ with message:
+ *   "Cannot translate {source}/{model} to {target} provider. Cross-provider model translation is not supported."
+ *
+ * @example
+ * ```ts
+ * // Same provider: pass-through
+ * const spec = parseModelSpec('anthropic/claude-3-5-sonnet');
+ * const model = formatModelForProvider(spec, 'anthropic');
+ * console.log(model); // "claude-3-5-sonnet"
+ *
+ * // Different provider: error
+ * try {
+ *   formatModelForProvider(spec, 'openai');
+ * } catch (error) {
+ *   console.error((error as Error).message);
+ *   // "Cannot translate anthropic/claude-3-5-sonnet to openai provider. ..."
+ * }
+ * ```
+ *
+ * @see {@link parseModelSpec} for creating ModelSpec objects
+ * @see {@link ModelSpec} for the input type structure
+ * @see {@link ModelProviderId} for the open provider set
+ */
+export declare function formatModelForProvider(spec: ModelSpec, targetProvider: ModelProviderId): string;
+//# sourceMappingURL=model-spec.d.ts.map

package/dist/utils/model-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-spec.d.ts","sourceRoot":"","sources":["../../src/utils/model-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,eAAe,GAAE,eAA6B,GAC7C,SAAS,CAiDX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,EACf,cAAc,EAAE,eAAe,GAC9B,MAAM,CAWR"}

package/dist/utils/model-spec.js

@@ -0,0 +1,149 @@
+/**
+ * Model specification parsing utility
+ *
+ * Provides parsing and validation of model specification strings
+ * per PRD §7.8 (Model & Provider Specification).
+ *
+ * The provider axis is an OPEN set (PRD §7.8): any non-empty provider string
+ * is valid. The harness (pi | claude-code) is NEVER part of the model string —
+ * harness-qualified strings (e.g. `pi/anthropic/x`) are rejected.
+ */
+/**
+ * Parse a model specification string into a ModelSpec object
+ *
+ * ## Supported Formats
+ *
+ * ### Qualified Format (provider/model)
+ * Explicit provider specification with "/" separator.
+ * - Input: `"anthropic/claude-3-5-sonnet"`
+ * - Output: `{ provider: 'anthropic', model: 'claude-3-5-sonnet', raw: 'anthropic/claude-3-5-sonnet' }`
+ *
+ * ### Plain Format (model only)
+ * Uses default provider when no provider specified.
+ * - Input: `"claude-sonnet-4"` with defaultProvider: `'anthropic'`
+ * - Output: `{ provider: 'anthropic', model: 'claude-sonnet-4', raw: 'claude-sonnet-4' }`
+ *
+ * ## Validation Rules
+ *
+ * 1. Input cannot be empty or whitespace-only
+ * 2. Provider must be a non-empty string (open set — any LLM provider accepted)
+ * 3. Model name cannot be empty after provider split
+ * 4. Harness-qualified strings (3+ segments, e.g. `pi/anthropic/x`) are REJECTED
+ *    (PRD §7.8 critical rule: the harness must never appear in the model string)
+ * 5. Input is trimmed before parsing, original preserved in `raw` field
+ *
+ * @param model - Model specification string to parse
+ * @param defaultProvider - Default provider to use when none specified (default: 'anthropic')
+ * @returns Parsed ModelSpec object with provider, model, and raw string
+ * @throws {Error} When model specification is invalid:
+ * - Empty or whitespace-only input
+ * - Empty provider or model parts
+ * - Harness-qualified strings (3+ segments)
+ *
+ * @example
+ * ```ts
+ * // Qualified format with known provider
+ * const spec1 = parseModelSpec('anthropic/claude-3-5-sonnet');
+ * // Returns: { provider: 'anthropic', model: 'claude-3-5-sonnet', raw: 'anthropic/claude-3-5-sonnet' }
+ *
+ * // Qualified format with custom provider (open set)
+ * const spec2 = parseModelSpec('openai/gpt-4o');
+ * // Returns: { provider: 'openai', model: 'gpt-4o', raw: 'openai/gpt-4o' }
+ *
+ * // Plain format — resolved against default provider
+ * const spec3 = parseModelSpec('claude-sonnet-4');
+ * // Returns: { provider: 'anthropic', model: 'claude-sonnet-4', raw: 'claude-sonnet-4' }
+ *
+ * // Harness-qualified — REJECTED (PRD §7.8 critical rule)
+ * parseModelSpec('pi/anthropic/claude-sonnet-4');
+ * // Throws: "Harness must not appear in model string …"
+ * ```
+ *
+ * @see {@link ModelSpec} for the return type structure
+ * @see {@link ModelProviderId} for the open provider set
+ */
+export function parseModelSpec(model, defaultProvider = 'anthropic') {
+    // Preserve ORIGINAL (untrimmed) input — existing consumers rely on raw being exact.
+    const raw = model;
+    // Trim for parsing — raw stays untouched.
+    const trimmed = model.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Model specification cannot be empty. Expected format: "provider/model" or "model"');
+    }
+    // Split WITHOUT a limit — must observe ALL segments to detect harness-qualified forms.
+    const parts = trimmed.split('/');
+    if (parts.length === 1) {
+        // Plain format — resolve against defaultProvider (open set).
+        return { provider: defaultProvider, model: parts[0], raw };
+    }
+    if (parts.length === 2) {
+        const [provider, modelName] = parts;
+        if (provider.length === 0) {
+            throw new Error(`Invalid model specification: "${trimmed}". ` +
+                'Provider cannot be empty. Expected format: "provider/model"');
+        }
+        if (modelName.length === 0) {
+            throw new Error(`Invalid model specification: "${trimmed}". ` +
+                'Model name cannot be empty. Expected format: "provider/model"');
+        }
+        // Open set: ANY non-empty provider string is a valid ModelProviderId (PRD §7.8).
+        // No closed-union check — the harness enforces provider constraints at initialize/execute.
+        return { provider, model: modelName, raw };
+    }
+    // parts.length >= 3 → harness-qualified form (e.g. pi/anthropic/x, cc/anthropic/...).
+    // PRD §7.8 critical rule: the harness must NEVER appear in the model string.
+    throw new Error(`Harness must not appear in model string. ` +
+        `Expected format "provider/model" (e.g. "anthropic/claude-sonnet-4-20250514"), got "${raw}".`);
+}
+/**
+ * Format a ModelSpec for a specific target provider
+ *
+ * ## Behavior
+ *
+ * ### Same Provider (Pass-Through)
+ * When `spec.provider` matches `targetProvider`, returns the model name only.
+ *
+ * **Example:**
+ * - Input: `{ provider: 'anthropic', model: 'claude-3-5-sonnet', raw: 'anthropic/claude-3-5-sonnet' }`, `'anthropic'`
+ * - Output: `"claude-3-5-sonnet"`
+ *
+ * ### Different Providers (Error)
+ * When providers differ, throws an error. Cross-provider model translation
+ * is not supported in the MVP.
+ *
+ * @param spec - ModelSpec from parseModelSpec() or Provider.normalizeModel()
+ * @param targetProvider - The provider to format the model for
+ * @returns Formatted model string for target provider (model name only)
+ * @throws {Error} When providers differ with message:
+ *   "Cannot translate {source}/{model} to {target} provider. Cross-provider model translation is not supported."
+ *
+ * @example
+ * ```ts
+ * // Same provider: pass-through
+ * const spec = parseModelSpec('anthropic/claude-3-5-sonnet');
+ * const model = formatModelForProvider(spec, 'anthropic');
+ * console.log(model); // "claude-3-5-sonnet"
+ *
+ * // Different provider: error
+ * try {
+ *   formatModelForProvider(spec, 'openai');
+ * } catch (error) {
+ *   console.error((error as Error).message);
+ *   // "Cannot translate anthropic/claude-3-5-sonnet to openai provider. ..."
+ * }
+ * ```
+ *
+ * @see {@link parseModelSpec} for creating ModelSpec objects
+ * @see {@link ModelSpec} for the input type structure
+ * @see {@link ModelProviderId} for the open provider set
+ */
+export function formatModelForProvider(spec, targetProvider) {
+    // Pass-through: same provider
+    if (spec.provider === targetProvider) {
+        return spec.model;
+    }
+    // Error: different providers (translation not supported in MVP).
+    throw new Error(`Cannot translate ${spec.provider}/${spec.model} to ${targetProvider} provider. ` +
+        'Cross-provider model translation is not supported.');
+}
+//# sourceMappingURL=model-spec.js.map

package/dist/utils/model-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-spec.js","sourceRoot":"","sources":["../../src/utils/model-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAa,EACb,kBAAmC,WAAW;IAE9C,oFAAoF;IACpF,MAAM,GAAG,GAAG,KAAK,CAAC;IAElB,0CAA0C;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAE7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,mFAAmF,CACpF,CAAC;IACJ,CAAC;IAED,uFAAuF;IACvF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAEjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,6DAA6D;QAC7D,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;IAC7D,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;QAEpC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,iCAAiC,OAAO,KAAK;gBAC7C,6DAA6D,CAC9D,CAAC;QACJ,CAAC;QAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,iCAAiC,OAAO,KAAK;gBAC7C,+DAA+D,CAChE,CAAC;QACJ,CAAC;QAED,iFAAiF;QACjF,2FAA2F;QAC3F,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;IAC7C,CAAC;IAED,sFAAsF;IACtF,6EAA6E;IAC7E,MAAM,IAAI,KAAK,CACb,2CAA2C;QAC3C,sFAAsF,GAAG,IAAI,CAC9F,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAe,EACf,cAA+B;IAE/B,8BAA8B;IAC9B,IAAI,IAAI,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,iEAAiE;IACjE,MAAM,IAAI,KAAK,CACb,oBAAoB,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,OAAO,cAAc,aAAa;QACjF,oDAAoD,CACrD,CAAC;AACJ,CAAC"}

package/dist/utils/observable.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Lightweight Observable implementation for event streaming
+ * No external dependencies
+ */
+export interface Subscription {
+    unsubscribe(): void;
+}
+export interface Observer<T> {
+    next?: (value: T) => void;
+    error?: (error: unknown) => void;
+    complete?: () => void;
+}
+/**
+ * Logger interface for Observable error logging
+ * Matches WorkflowLogger.error() signature for compatibility
+ */
+export interface ObservableLogger {
+    error(message: string, data?: unknown): void;
+}
+export declare class Observable<T> {
+    private subscribers;
+    private logger?;
+    /**
+     * Create a new Observable
+     * @param logger Optional logger for error reporting (falls back to console.error)
+     */
+    constructor(logger?: ObservableLogger);
+    /**
+     * Subscribe to this observable
+     * @returns Subscription with unsubscribe method
+     */
+    subscribe(observer: Observer<T>): Subscription;
+    /**
+     * Log errors using injected logger or fallback to console.error
+     */
+    private logError;
+    /**
+     * Emit a value to all subscribers
+     */
+    next(value: T): void;
+    /**
+     * Signal an error to all subscribers
+     */
+    error(err: unknown): void;
+    /**
+     * Signal completion to all subscribers
+     */
+    complete(): void;
+    /**
+     * Get current subscriber count
+     */
+    get subscriberCount(): number;
+}
+//# sourceMappingURL=observable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"observable.d.ts","sourceRoot":"","sources":["../../src/utils/observable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC1B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,MAAM,CAAC,CAAmB;IAElC;;;OAGG;gBACS,MAAM,CAAC,EAAE,gBAAgB;IAIrC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,YAAY;IAS9C;;OAEG;IACH,OAAO,CAAC,QAAQ;IAShB;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAUpB;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAUzB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAWhB;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;CACF"}

package/dist/utils/observable.js

@@ -0,0 +1,82 @@
+export class Observable {
+    subscribers = new Set();
+    logger;
+    /**
+     * Create a new Observable
+     * @param logger Optional logger for error reporting (falls back to console.error)
+     */
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Subscribe to this observable
+     * @returns Subscription with unsubscribe method
+     */
+    subscribe(observer) {
+        this.subscribers.add(observer);
+        return {
+            unsubscribe: () => {
+                this.subscribers.delete(observer);
+            },
+        };
+    }
+    /**
+     * Log errors using injected logger or fallback to console.error
+     */
+    logError(message, error) {
+        if (this.logger) {
+            this.logger.error(message, { error });
+        }
+        else {
+            // Fallback for backward compatibility
+            console.error(message, error);
+        }
+    }
+    /**
+     * Emit a value to all subscribers
+     */
+    next(value) {
+        for (const subscriber of this.subscribers) {
+            try {
+                subscriber.next?.(value);
+            }
+            catch (err) {
+                this.logError('Observable subscriber error', err);
+            }
+        }
+    }
+    /**
+     * Signal an error to all subscribers
+     */
+    error(err) {
+        for (const subscriber of this.subscribers) {
+            try {
+                subscriber.error?.(err);
+            }
+            catch (e) {
+                this.logError('Observable error handler failed', e);
+            }
+        }
+    }
+    /**
+     * Signal completion to all subscribers
+     */
+    complete() {
+        for (const subscriber of this.subscribers) {
+            try {
+                subscriber.complete?.();
+            }
+            catch (err) {
+                this.logError('Observable complete handler failed', err);
+            }
+        }
+        this.subscribers.clear();
+    }
+    /**
+     * Get current subscriber count
+     */
+    get subscriberCount() {
+        return this.subscribers.size;
+    }
+}
+//# sourceMappingURL=observable.js.map

package/dist/utils/observable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observable.js","sourceRoot":"","sources":["../../src/utils/observable.ts"],"names":[],"mappings":"AAsBA,MAAM,OAAO,UAAU;IACb,WAAW,GAAqB,IAAI,GAAG,EAAE,CAAC;IAC1C,MAAM,CAAoB;IAElC;;;OAGG;IACH,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,QAAqB;QAC7B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC/B,OAAO;YACL,WAAW,EAAE,GAAG,EAAE;gBAChB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACpC,CAAC;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,QAAQ,CAAC,OAAe,EAAE,KAAc;QAC9C,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,KAAQ;QACX,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAC1C,IAAI,CAAC;gBACH,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;YAC3B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,QAAQ,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAY;QAChB,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAC1C,IAAI,CAAC;gBACH,UAAU,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,QAAQ,CAAC,iCAAiC,EAAE,CAAC,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAC1C,IAAI,CAAC;gBACH,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC;YAC1B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,QAAQ,CAAC,oCAAoC,EAAE,GAAG,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IAC/B,CAAC;CACF"}

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

@@ -0,0 +1,10 @@
+/**
+ * Global provider configuration — DEPRECATED shim.
+ *
+ * @deprecated Since v1.2. All logic has moved to {@link ./harness-config.js}.
+ * Use `configureHarnesses` / `getGlobalHarnessConfig` / `resolveHarnessConfig` directly.
+ * This module remains only so existing imports (agent.ts, utils/index.ts, tests) keep
+ * resolving during the harness-vocabulary migration. Removed when P3.M1 rewires agent.ts.
+ */
+export { configureProviders, getGlobalProviderConfig, resolveProviderConfig, resetGlobalConfig, } from './harness-config.js';
+//# sourceMappingURL=provider-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider-config.d.ts","sourceRoot":"","sources":["../../src/utils/provider-config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC"}

package/dist/utils/provider-config.js

@@ -0,0 +1,10 @@
+/**
+ * Global provider configuration — DEPRECATED shim.
+ *
+ * @deprecated Since v1.2. All logic has moved to {@link ./harness-config.js}.
+ * Use `configureHarnesses` / `getGlobalHarnessConfig` / `resolveHarnessConfig` directly.
+ * This module remains only so existing imports (agent.ts, utils/index.ts, tests) keep
+ * resolving during the harness-vocabulary migration. Removed when P3.M1 rewires agent.ts.
+ */
+export { configureProviders, getGlobalProviderConfig, resolveProviderConfig, resetGlobalConfig, } from './harness-config.js';
+//# sourceMappingURL=provider-config.js.map

package/dist/utils/provider-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-config.js","sourceRoot":"","sources":["../../src/utils/provider-config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC"}

package/dist/utils/restart-analysis.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Error analysis utilities for step restart decisions
+ *
+ * Provides pure, side-effect-free functions for analyzing WorkflowError instances
+ * to determine if a step should be restarted, with structured restart analysis
+ * including reason, suggested action, and success probability estimation.
+ *
+ * @module restart-analysis
+ */
+import type { WorkflowError } from '../types/error.js';
+import type { RestartAnalysis, ErrorCriterion } from '../types/restart.js';
+/**
+ * Transient error codes that typically indicate temporary failures
+ *
+ * These errors are usually resolved by retrying the operation after a delay.
+ * The constant uses const assertion for type safety and better TypeScript inference.
+ *
+ * **Error Categories:**
+ * - `TIMEOUT`: Operation timed out waiting for response
+ * - `RATE_LIMIT`: API rate limit exceeded (HTTP 429)
+ * - `NETWORK_ERROR`: Network connectivity issues
+ * - `SERVICE_UNAVAILABLE`: Service temporarily unavailable (HTTP 503)
+ *
+ * @example
+ * ```ts
+ * if (TRANSIENT_ERROR_SET.has('TIMEOUT')) {
+ *   // This is a transient error, safe to retry
+ * }
+ * ```
+ */
+declare const TRANSIENT_ERROR_CODES: readonly ["TIMEOUT", "RATE_LIMIT", "NETWORK_ERROR", "SERVICE_UNAVAILABLE"];
+/**
+ * Set-based lookup for O(1) transient error code checking
+ *
+ * Using a Set provides constant-time lookup performance compared to
+ * array includes() which is O(n). This is important for hot paths
+ * in retry logic.
+ */
+declare const TRANSIENT_ERROR_SET: Set<"TIMEOUT" | "RATE_LIMIT" | "NETWORK_ERROR" | "SERVICE_UNAVAILABLE">;
+/**
+ * Analyze a WorkflowError to determine if a step should be restarted
+ *
+ * This is a pure, side-effect-free function that provides intelligent error
+ * analysis for step retry decisions. It returns a structured `RestartAnalysis`
+ * object with the restart decision, reasoning, suggested action, and success
+ * probability estimation.
+ *
+ * **Analysis Flow:**
+ * 1. Check `error.original?.recoverable` - if `false`, return abort immediately
+ * 2. Check if error is transient - if yes, return retry with high probability
+ * 3. If `stepOptions.retryOn` provided, iterate through criteria
+ * 4. For each criterion, call `matchesCriterion(error, criterion)`
+ * 5. If any criterion matches, return restart with analysis
+ * 6. Default: return no restart with abort action
+ *
+ * **Pure Function Guarantee:**
+ * - Deterministic: Same input always produces same output
+ * - No side effects: Doesn't modify inputs or external state
+ * - No external dependencies: Doesn't use Date.now(), Math.random(), etc.
+ *
+ * @param error - The WorkflowError to analyze
+ * @param stepOptions - Optional step configuration with retry criteria
+ * @returns Structured restart analysis with decision and reasoning
+ *
+ * @example Transient error - automatic restart
+ * ```ts
+ * const error: WorkflowError = {
+ *   message: 'TIMEOUT',
+ *   original: new Error('Request timeout'),
+ *   workflowId: 'wf-123',
+ *   state: {},
+ *   logs: []
+ * };
+ *
+ * const analysis = analyzeErrorForRestart(error);
+ * // Returns:
+ * // {
+ * //   shouldRestart: true,
+ * //   reason: 'Transient error detected: TIMEOUT',
+ * //   suggestedAction: 'retry',
+ * //   estimatedSuccessProbability: 0.8
+ * // }
+ * ```
+ *
+ * @example Non-recoverable error - abort
+ * ```ts
+ * const error: WorkflowError = {
+ *   message: 'Invalid configuration',
+ *   original: { recoverable: false },
+ *   workflowId: 'wf-123',
+ *   state: {},
+ *   logs: []
+ * };
+ *
+ * const analysis = analyzeErrorForRestart(error);
+ * // Returns:
+ * // {
+ * //   shouldRestart: false,
+ * //   reason: 'Error is marked as non-recoverable: Invalid configuration',
+ * //   suggestedAction: 'abort',
+ * //   estimatedSuccessProbability: 0.0
+ * // }
+ * ```
+ *
+ * @example Custom retry criteria
+ * ```ts
+ * const error: WorkflowError = {
+ *   message: 'ETIMEDOUT',
+ *   original: new Error('Connection timeout'),
+ *   workflowId: 'wf-123',
+ *   state: {},
+ *   logs: []
+ * };
+ *
+ * const stepOptions = {
+ *   retryOn: [
+ *     { code: 'ETIMEDOUT' },
+ *     { code: /NETWORK_ERROR/ },
+ *     { recoverable: true }
+ *   ]
+ * };
+ *
+ * const analysis = analyzeErrorForRestart(error, stepOptions);
+ * // Returns:
+ * // {
+ * //   shouldRestart: true,
+ * //   reason: 'Error matches retry criteria: ETIMEDOUT',
+ * //   suggestedAction: 'retry',
+ * //   estimatedSuccessProbability: 0.5
+ * // }
+ * ```
+ *
+ * @example No matching criteria - default abort
+ * ```ts
+ * const error: WorkflowError = {
+ *   message: 'AUTH_FAILED',
+ *   original: new Error('Authentication failed'),
+ *   workflowId: 'wf-123',
+ *   state: {},
+ *   logs: []
+ * };
+ *
+ * const stepOptions = {
+ *   retryOn: [{ code: 'TIMEOUT' }]
+ * };
+ *
+ * const analysis = analyzeErrorForRestart(error, stepOptions);
+ * // Returns:
+ * // {
+ * //   shouldRestart: false,
+ * //   reason: 'No matching retry criteria for error: AUTH_FAILED',
+ * //   suggestedAction: 'abort',
+ * //   estimatedSuccessProbability: 0.0
+ * // }
+ * ```
+ *
+ * @remarks
+ * **Integration with @Step Decorator:**
+ * This function is designed to be used by the @Step decorator's retry loop
+ * (src/decorators/step.ts:115-228) to provide structured analysis for
+ * stepRetry events.
+ *
+ * **ErrorCriterion Pattern:**
+ * The function follows the existing pattern in src/decorators/step.ts:40-65
+ * for matching criteria against errors.
+ *
+ * **Gotchas:**
+ * - WorkflowError doesn't have a 'code' property - uses message as fallback
+ * - Always check `typeof criterion === 'function'` FIRST for type safety
+ * - Check error.original?.recoverable for recoverable flag
+ *
+ * @see {@link RestartAnalysis} - Return type structure
+ * @see {@link ErrorCriterion} - Retry criterion types
+ * @see {@link WorkflowError} - Input error type
+ */
+export declare function analyzeErrorForRestart(error: WorkflowError, stepOptions?: {
+    retryOn?: ErrorCriterion[];
+}): RestartAnalysis;
+/**
+ * Transient error codes constant
+ *
+ * Exported for testing and external use. Use TRANSIENT_ERROR_SET
+ * for O(1) lookup performance.
+ *
+ * @example
+ * ```ts
+ * import { TRANSIENT_ERROR_CODES } from './restart-analysis.js';
+ *
+ * if (TRANSIENT_ERROR_CODES.includes('TIMEOUT')) {
+ *   // Handle transient error
+ * }
+ * ```
+ */
+export { TRANSIENT_ERROR_CODES };
+/**
+ * Transient error code set for O(1) lookup
+ *
+ * Exported for testing and external use. Prefer this over
+ * TRANSIENT_ERROR_CODES for performance-critical code.
+ */
+export { TRANSIENT_ERROR_SET };
+//# sourceMappingURL=restart-analysis.d.ts.map

package/dist/utils/restart-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart-analysis.d.ts","sourceRoot":"","sources":["../../src/utils/restart-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;GAkBG;AACH,QAAA,MAAM,qBAAqB,4EAKjB,CAAC;AAEX;;;;;;GAMG;AACH,QAAA,MAAM,mBAAmB,yEAAiC,CAAC;AAmM3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,WAAW,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,cAAc,EAAE,CAAA;CAAE,GAC3C,eAAe,CA2CjB;AAED;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC;;;;;GAKG;AACH,OAAO,EAAE,mBAAmB,EAAE,CAAC"}