groundswell 0.0.3 → 1.0.0

package/dist/utils/harness-config.js

@@ -0,0 +1,311 @@
+/**
+ * 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
+ */
+// ============================================================================
+// Harness Cascade — Module-Private Storage
+// ============================================================================
+/**
+ * Module-private harness configuration singleton.
+ *
+ * Not exported — access via `getGlobalHarnessConfig()` / `configureHarnesses()`.
+ * @internal
+ */
+let globalHarnessConfig = null;
+/**
+ * Default harness configuration (PRD §7.1 — `pi` is the vendor-neutral default).
+ * @internal
+ */
+const DEFAULT_HARNESS_CONFIG = {
+    defaultHarness: 'pi',
+};
+// ============================================================================
+// Harness Cascade — Validation Helpers
+// ============================================================================
+/**
+ * Type guard: checks if a string is a valid `HarnessId` ('pi' | 'claude-code').
+ */
+function isValidHarnessId(value) {
+    return value === 'pi' || value === 'claude-code';
+}
+/**
+ * Formatted list of supported harnesses for error messages.
+ */
+function getSupportedHarnessesList() {
+    return '"pi", "claude-code"';
+}
+// ============================================================================
+// Harness Cascade — Public API
+// ============================================================================
+/**
+ * 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 function configureHarnesses(config) {
+    // Validate defaultHarness
+    if (!isValidHarnessId(config.defaultHarness)) {
+        throw new Error(`Invalid default harness: "${config.defaultHarness}". ` +
+            `Supported harnesses: ${getSupportedHarnessesList()}`);
+    }
+    // Validate harnessDefaults keys (if present)
+    if (config.harnessDefaults) {
+        for (const id of Object.keys(config.harnessDefaults)) {
+            if (!isValidHarnessId(id)) {
+                throw new Error(`Invalid harness in harnessDefaults: "${id}". ` +
+                    `Supported harnesses: ${getSupportedHarnessesList()}`);
+            }
+        }
+    }
+    // Store configuration (defaultModelProvider is open set — no validation)
+    globalHarnessConfig = config;
+}
+/**
+ * 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 function getGlobalHarnessConfig() {
+    return globalHarnessConfig ?? DEFAULT_HARNESS_CONFIG;
+}
+/**
+ * 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 function resolveHarnessConfig(globalConfig, agentHarness, agentOptions, promptHarness, promptOptions) {
+    // Step 1: Resolve harness — prompt wins (first-defined-wins via ??)
+    const harness = promptHarness ?? agentHarness ?? globalConfig.defaultHarness;
+    // Step 2: Get global defaults for the resolved harness
+    const globalDefaults = globalConfig.harnessDefaults?.[harness];
+    // Step 3: Merge options — last write wins
+    const options = {
+        ...(globalDefaults ?? {}),
+        ...(agentOptions ?? {}),
+        ...(promptOptions ?? {}),
+    };
+    return { harness, options };
+}
+/**
+ * Reset the global harness configuration to defaults.
+ *
+ * **FOR TESTING PURPOSES ONLY.**
+ *
+ * @internal
+ */
+export function resetGlobalHarnessConfig() {
+    globalHarnessConfig = null;
+}
+// ============================================================================
+// Deprecated Legacy Aliases — Module-Private Storage (Separate Singleton)
+// ============================================================================
+/**
+ * Module-private LEGACY provider configuration singleton.
+ *
+ * **Separate from `globalHarnessConfig`** — the two validate disjoint id sets
+ * (see module-level Scope Decision). This singleton is owned by the deprecated
+ * `configureProviders` / `getGlobalProviderConfig` / `resetGlobalConfig` functions.
+ * @internal
+ */
+let globalProviderConfig = null;
+/**
+ * Default LEGACY provider configuration.
+ * @internal
+ */
+const DEFAULT_PROVIDER_CONFIG = {
+    defaultProvider: 'anthropic',
+    providerDefaults: undefined,
+};
+// ============================================================================
+// Deprecated Legacy Aliases — Validation Helpers
+// ============================================================================
+/**
+ * Type guard: checks if a string is a valid `ProviderId`.
+ *
+ * Accepts 'anthropic' (legacy), 'pi', and 'claude-code'.
+ */
+function isValidProviderId(value) {
+    return value === 'anthropic' || value === 'pi' || value === 'claude-code';
+}
+/**
+ * Formatted list of supported providers for LEGACY error messages.
+ */
+function getSupportedProvidersList() {
+    return '"anthropic", "pi", "claude-code"';
+}
+// ============================================================================
+// Deprecated Legacy Aliases — Public API
+// ============================================================================
+/**
+ * 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 function configureProviders(config) {
+    // Step 1: Validate defaultProvider
+    if (!isValidProviderId(config.defaultProvider)) {
+        throw new Error(`Invalid default provider: "${config.defaultProvider}". ` +
+            `Supported providers: ${getSupportedProvidersList()}`);
+    }
+    // Step 2: Validate providerDefaults keys (if present)
+    if (config.providerDefaults) {
+        for (const providerId of Object.keys(config.providerDefaults)) {
+            if (!isValidProviderId(providerId)) {
+                throw new Error(`Invalid provider in providerDefaults: "${providerId}". ` +
+                    `Supported providers: ${getSupportedProvidersList()}`);
+            }
+        }
+    }
+    // Step 3: Store configuration in the LEGACY singleton (NOT configureHarnesses)
+    globalProviderConfig = config;
+}
+/**
+ * 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 function getGlobalProviderConfig() {
+    return globalProviderConfig ?? DEFAULT_PROVIDER_CONFIG;
+}
+/**
+ * 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 function resolveProviderConfig(globalConfig, agentProvider, agentOptions, promptProvider, promptOptions) {
+    // Translate GlobalProviderConfig → GlobalHarnessConfig shape (unsound but runtime-safe casts)
+    const harnessGlobal = {
+        defaultHarness: globalConfig.defaultProvider,
+        harnessDefaults: globalConfig.providerDefaults,
+    };
+    // Delegate to resolveHarnessConfig (pure function — no singleton coupling)
+    const { harness, options } = resolveHarnessConfig(harnessGlobal, agentProvider, agentOptions, promptProvider, promptOptions);
+    // Map back to legacy shape
+    return { provider: harness, options: options };
+}
+/**
+ * Reset global configuration to defaults.
+ *
+ * @deprecated Since v1.2. Use {@link resetGlobalHarnessConfig}.
+ *
+ * **FOR TESTING PURPOSES ONLY.**
+ *
+ * @internal
+ */
+export function resetGlobalConfig() {
+    globalProviderConfig = null;
+}
+//# sourceMappingURL=harness-config.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"harness-config.js","sourceRoot":"","sources":["../../src/utils/harness-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAgBH,+EAA+E;AAC/E,2CAA2C;AAC3C,+EAA+E;AAE/E;;;;;GAKG;AACH,IAAI,mBAAmB,GAA+B,IAAI,CAAC;AAE3D;;;GAGG;AACH,MAAM,sBAAsB,GAAwB;IAClD,cAAc,EAAE,IAAiB;CAClC,CAAC;AAEF,+EAA+E;AAC/E,uCAAuC;AACvC,+EAA+E;AAE/E;;GAEG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,aAAa,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,SAAS,yBAAyB;IAChC,OAAO,qBAAqB,CAAC;AAC/B,CAAC;AAED,+EAA+E;AAC/E,+BAA+B;AAC/B,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA2B;IAC5D,0BAA0B;IAC1B,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,6BAA6B,MAAM,CAAC,cAAc,KAAK;YACvD,wBAAwB,yBAAyB,EAAE,EAAE,CACtD,CAAC;IACJ,CAAC;IAED,6CAA6C;IAC7C,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;QAC3B,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC;YACrD,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,wCAAwC,EAAE,KAAK;oBAC/C,wBAAwB,yBAAyB,EAAE,EAAE,CACtD,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,mBAAmB,GAAG,MAAM,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,mBAAmB,IAAI,sBAAsB,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,oBAAoB,CAClC,YAAiC,EACjC,YAAwB,EACxB,YAA6B,EAC7B,aAAyB,EACzB,aAA8B;IAE9B,oEAAoE;IACpE,MAAM,OAAO,GAAG,aAAa,IAAI,YAAY,IAAI,YAAY,CAAC,cAAc,CAAC;IAE7E,uDAAuD;IACvD,MAAM,cAAc,GAAG,YAAY,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,CAAC;IAE/D,0CAA0C;IAC1C,MAAM,OAAO,GAAmB;QAC9B,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;QACzB,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC;QACvB,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC;KACzB,CAAC;IAEF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB;IACtC,mBAAmB,GAAG,IAAI,CAAC;AAC7B,CAAC;AAED,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAE/E;;;;;;;GAOG;AACH,IAAI,oBAAoB,GAAgC,IAAI,CAAC;AAE7D;;;GAGG;AACH,MAAM,uBAAuB,GAAyB;IACpD,eAAe,EAAE,WAAyB;IAC1C,gBAAgB,EAAE,SAAS;CAC5B,CAAC;AAEF,+EAA+E;AAC/E,iDAAiD;AACjD,+EAA+E;AAE/E;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,aAAa,CAAC;AAC5E,CAAC;AAED;;GAEG;AACH,SAAS,yBAAyB;IAChC,OAAO,kCAAkC,CAAC;AAC5C,CAAC;AAED,+EAA+E;AAC/E,yCAAyC;AACzC,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA4B;IAC7D,mCAAmC;IACnC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,8BAA8B,MAAM,CAAC,eAAe,KAAK;YACzD,wBAAwB,yBAAyB,EAAE,EAAE,CACtD,CAAC;IACJ,CAAC;IAED,sDAAsD;IACtD,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC5B,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAC9D,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACb,0CAA0C,UAAU,KAAK;oBACzD,wBAAwB,yBAAyB,EAAE,EAAE,CACtD,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,oBAAoB,GAAG,MAAM,CAAC;AAChC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,oBAAoB,IAAI,uBAAuB,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,qBAAqB,CACnC,YAAkC,EAClC,aAA0B,EAC1B,YAA8B,EAC9B,cAA2B,EAC3B,aAA+B;IAE/B,8FAA8F;IAC9F,MAAM,aAAa,GAAwB;QACzC,cAAc,EAAE,YAAY,CAAC,eAA4B;QACzD,eAAe,EACb,YAAY,CAAC,gBAA0E;KAC1F,CAAC;IAEF,2EAA2E;IAC3E,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,oBAAoB,CAC/C,aAAa,EACb,aAAsC,EACtC,YAA0C,EAC1C,cAAuC,EACvC,aAA2C,CAC5C,CAAC;IAEF,2BAA2B;IAC3B,OAAO,EAAE,QAAQ,EAAE,OAAqB,EAAE,OAAO,EAAE,OAA0B,EAAE,CAAC;AAClF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB;IAC/B,oBAAoB,GAAG,IAAI,CAAC;AAC9B,CAAC"}

package/dist/utils/index.d.ts

@@ -1,5 +1,13 @@
+export { analyzeErrorForRestart, TRANSIENT_ERROR_CODES, TRANSIENT_ERROR_SET } from './restart-analysis.js';
+export { validateAgentResponse } from './agent-validation.js';
+export { configureProviders } from './provider-config.js';
+export { configureHarnesses, getGlobalHarnessConfig, resolveHarnessConfig, resetGlobalHarnessConfig } from './harness-config.js';
+export { delay } from './delay.js';
 export { generateId } from './id.js';
-export { Observable } from './observable.js';
 export { mergeWorkflowErrors } from './workflow-error-utils.js';
+export { parseModelSpec, formatModelForProvider } from './model-spec.js';
+export { Observable } from './observable.js';
 export type { Subscription, Observer } from './observable.js';
+export type { ValidationResult } from './agent-validation.js';
+export { serializeSession, deserializeSession, SessionSerializationError } from './session-serialization.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC3G,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACjI,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/utils/index.js

@@ -1,4 +1,11 @@
+export { analyzeErrorForRestart, TRANSIENT_ERROR_CODES, TRANSIENT_ERROR_SET } from './restart-analysis.js';
+export { validateAgentResponse } from './agent-validation.js';
+export { configureProviders } from './provider-config.js';
+export { configureHarnesses, getGlobalHarnessConfig, resolveHarnessConfig, resetGlobalHarnessConfig } from './harness-config.js';
+export { delay } from './delay.js';
 export { generateId } from './id.js';
-export { Observable } from './observable.js';
 export { mergeWorkflowErrors } from './workflow-error-utils.js';
+export { parseModelSpec, formatModelForProvider } from './model-spec.js';
+export { Observable } from './observable.js';
+export { serializeSession, deserializeSession, SessionSerializationError } from './session-serialization.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC3G,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACjI,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC"}

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/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"}