conatus 0.1.0

package/dist/drive/stall-detector.js

@@ -0,0 +1,378 @@
+import { StallReportSchema, StallStateSchema, StallAnalysisSchema } from "../types/stall.js";
+import { DEFAULT_CHARACTER_CONFIG } from "../types/character.js";
+// ─── Base feedback category → N loops mapping (at stall_flexibility=1, multiplier=1.0) ───
+const BASE_FEEDBACK_CATEGORY_N = {
+    immediate: 6,
+    medium_term: 5,
+    long_term: 10,
+};
+const BASE_DEFAULT_N = 5;
+// ─── Minimum score-improvement delta to reset stall detection ───
+// Improvements smaller than this are treated as noise (no reset).
+const MIN_IMPROVEMENT_DELTA = 0.05;
+// ─── Time thresholds ───
+const DEFAULT_DURATION_HOURS_BY_CATEGORY = {
+    coding: 2,
+    implementation: 2,
+    research: 4,
+    investigation: 4,
+};
+const DEFAULT_DURATION_HOURS_FALLBACK = 3;
+// ─── Stall thresholds ───
+const CONSECUTIVE_FAILURE_THRESHOLD = 3;
+const ESCALATION_CAP = 3;
+// ─── Decay factor constants ───
+const DECAY_FACTOR_STALLED = 0.6;
+const RECOVERY_SCHEDULE = [
+    { loops: 0, factor: 0.75 },
+    { loops: 2, factor: 0.9 },
+    { loops: 4, factor: 1.0 },
+];
+/**
+ * StallDetector detects stalls (circuit breaker) in the Motiva orchestrator loop.
+ * Supports 4 stall types: dimension_stall, time_exceeded, consecutive_failure, global_stall.
+ */
+export class StallDetector {
+    stateManager;
+    characterConfig;
+    constructor(stateManager, characterConfig) {
+        this.stateManager = stateManager;
+        this.characterConfig = characterConfig ?? DEFAULT_CHARACTER_CONFIG;
+    }
+    /**
+     * Return the adjusted N value for a given feedback category.
+     * stall_flexibility=1 (default, most flexible) → multiplier=1.0 (pivot fast)
+     * stall_flexibility=5 (most persistent) → multiplier=2.0
+     * Formula: multiplier = 0.75 + (stall_flexibility * 0.25)
+     */
+    getAdjustedN(category) {
+        const multiplier = 0.75 + this.characterConfig.stall_flexibility * 0.25;
+        const base = category
+            ? (BASE_FEEDBACK_CATEGORY_N[category] ?? BASE_DEFAULT_N)
+            : BASE_DEFAULT_N;
+        return Math.round(base * multiplier);
+    }
+    // ─── Public Methods ───
+    /**
+     * Check if a single dimension's gap has not improved for N loops.
+     * N is determined by the feedbackCategory (immediate/medium_term/long_term).
+     */
+    checkDimensionStall(goalId, dimensionName, gapHistory, feedbackCategory) {
+        const n = this.getAdjustedN(feedbackCategory);
+        if (gapHistory.length < n + 1) {
+            // Not enough history to determine a stall
+            return null;
+        }
+        const recent = gapHistory.slice(-n - 1);
+        const oldest = recent[0].normalized_gap;
+        const latest = recent[recent.length - 1].normalized_gap;
+        // "No improvement" = latest gap has not decreased by at least MIN_IMPROVEMENT_DELTA
+        // Trivial improvements (< 0.05) are treated as noise and do not reset stall detection.
+        if (oldest - latest >= MIN_IMPROVEMENT_DELTA) {
+            return null; // meaningful improvement
+        }
+        return StallReportSchema.parse({
+            stall_type: "dimension_stall",
+            goal_id: goalId,
+            dimension_name: dimensionName,
+            task_id: null,
+            detected_at: new Date().toISOString(),
+            escalation_level: 0,
+            suggested_cause: "approach_failure",
+            decay_factor: DECAY_FACTOR_STALLED,
+        });
+    }
+    /**
+     * Check if a task has exceeded its time threshold (estimate × 2, or default by category).
+     */
+    checkTimeExceeded(task) {
+        if (!task.started_at) {
+            return null;
+        }
+        const startedAt = new Date(task.started_at);
+        const now = new Date();
+        const elapsedMs = now.getTime() - startedAt.getTime();
+        const elapsedHours = elapsedMs / (1000 * 60 * 60);
+        const thresholdHours = this.computeTimeThreshold(task.estimated_duration, task.task_category);
+        if (elapsedHours <= thresholdHours) {
+            return null;
+        }
+        return StallReportSchema.parse({
+            stall_type: "time_exceeded",
+            goal_id: task.goal_id,
+            dimension_name: null,
+            task_id: task.task_id ?? null,
+            detected_at: new Date().toISOString(),
+            escalation_level: 0,
+            suggested_cause: "external_dependency",
+            decay_factor: DECAY_FACTOR_STALLED,
+        });
+    }
+    /**
+     * Check if a dimension has had 3+ consecutive failures.
+     */
+    checkConsecutiveFailures(goalId, dimensionName, consecutiveFailureCount) {
+        if (consecutiveFailureCount < CONSECUTIVE_FAILURE_THRESHOLD) {
+            return null;
+        }
+        return StallReportSchema.parse({
+            stall_type: "consecutive_failure",
+            goal_id: goalId,
+            dimension_name: dimensionName,
+            task_id: null,
+            detected_at: new Date().toISOString(),
+            escalation_level: 0,
+            suggested_cause: "approach_failure",
+            decay_factor: DECAY_FACTOR_STALLED,
+        });
+    }
+    /**
+     * Check if ALL dimensions show no improvement for loopThreshold loops.
+     * Returns null if any dimension improved.
+     */
+    checkGlobalStall(goalId, allDimensionGaps, loopThreshold = this.getAdjustedN()) {
+        if (allDimensionGaps.size === 0) {
+            return null;
+        }
+        for (const [, gapHistory] of allDimensionGaps) {
+            if (gapHistory.length < loopThreshold + 1) {
+                // Not enough data for this dimension — treat as not stalled (insufficient evidence)
+                return null;
+            }
+            const recent = gapHistory.slice(-loopThreshold - 1);
+            const oldest = recent[0].normalized_gap;
+            const latest = recent[recent.length - 1].normalized_gap;
+            if (oldest - latest >= MIN_IMPROVEMENT_DELTA) {
+                // At least one dimension improved meaningfully — not a global stall
+                return null;
+            }
+        }
+        // All dimensions are non-improving
+        return StallReportSchema.parse({
+            stall_type: "global_stall",
+            goal_id: goalId,
+            dimension_name: null,
+            task_id: null,
+            detected_at: new Date().toISOString(),
+            escalation_level: 0,
+            suggested_cause: "goal_infeasible",
+            decay_factor: DECAY_FACTOR_STALLED,
+        });
+    }
+    /**
+     * Classify the root cause of a stall based on stall type and goal context.
+     */
+    classifyStallCause(stallType, goal) {
+        // Check for low-confidence dimensions → information_deficit
+        const hasLowConfidence = goal.dimensions?.some((d) => d.confidence !== undefined && d.confidence < 0.5);
+        if (hasLowConfidence) {
+            return "information_deficit";
+        }
+        switch (stallType) {
+            case "dimension_stall":
+                return "approach_failure";
+            case "time_exceeded":
+                return "external_dependency";
+            case "consecutive_failure":
+                return "approach_failure";
+            case "global_stall":
+                return "goal_infeasible";
+            default:
+                return "approach_failure";
+        }
+    }
+    /**
+     * Analyze the root cause of a stall from gap history.
+     * Returns a StallAnalysis with cause, confidence, evidence, and recommended_action.
+     *
+     * Patterns:
+     *   - oscillating (high variance, stable mean) → parameter_issue → REFINE
+     *   - flat (near-zero variance, near-zero delta) → strategy_wrong → PIVOT
+     *   - diverging (monotonically increasing trend) → goal_unreachable → ESCALATE
+     *   - fallback (unclear) → strategy_wrong → PIVOT
+     */
+    analyzeStallCause(gapHistory) {
+        const MIN_ENTRIES = 3;
+        if (gapHistory.length < MIN_ENTRIES) {
+            return StallAnalysisSchema.parse({
+                cause: "strategy_wrong",
+                confidence: 0.3,
+                evidence: `Insufficient history (${gapHistory.length} entries, need ${MIN_ENTRIES})`,
+                recommended_action: "pivot",
+            });
+        }
+        const gaps = gapHistory.map((e) => e.normalized_gap);
+        const n = gaps.length;
+        // Mean
+        const mean = gaps.reduce((s, v) => s + v, 0) / n;
+        // Variance
+        const variance = gaps.reduce((s, v) => s + (v - mean) ** 2, 0) / n;
+        // Delta (latest − oldest, positive means gap grew = worse)
+        const delta = gaps[n - 1] - gaps[0];
+        // Check divergence: monotonically increasing (gap grows each step)
+        let monotonicallyIncreasing = true;
+        for (let i = 1; i < n; i++) {
+            if (gaps[i] <= gaps[i - 1]) {
+                monotonicallyIncreasing = false;
+                break;
+            }
+        }
+        if (monotonicallyIncreasing && delta > 0.05) {
+            return StallAnalysisSchema.parse({
+                cause: "goal_unreachable",
+                confidence: 0.8,
+                evidence: `Gap is monotonically increasing (delta=${delta.toFixed(3)})`,
+                recommended_action: "escalate",
+            });
+        }
+        // Check oscillation: high variance + mean stays stable (|delta| small)
+        const HIGH_VARIANCE_THRESHOLD = 0.01;
+        const STABLE_DELTA_THRESHOLD = 0.05;
+        if (variance > HIGH_VARIANCE_THRESHOLD && Math.abs(delta) < STABLE_DELTA_THRESHOLD) {
+            return StallAnalysisSchema.parse({
+                cause: "parameter_issue",
+                confidence: 0.75,
+                evidence: `Oscillating gap (variance=${variance.toFixed(4)}, delta=${delta.toFixed(3)})`,
+                recommended_action: "refine",
+            });
+        }
+        // Check flat: very low variance + small delta
+        const LOW_VARIANCE_THRESHOLD = 0.005;
+        const LOW_DELTA_THRESHOLD = 0.05;
+        if (variance <= LOW_VARIANCE_THRESHOLD && Math.abs(delta) < LOW_DELTA_THRESHOLD) {
+            return StallAnalysisSchema.parse({
+                cause: "strategy_wrong",
+                confidence: 0.75,
+                evidence: `Flat gap with no progress (variance=${variance.toFixed(4)}, delta=${delta.toFixed(3)})`,
+                recommended_action: "pivot",
+            });
+        }
+        // Default fallback
+        return StallAnalysisSchema.parse({
+            cause: "strategy_wrong",
+            confidence: 0.5,
+            evidence: `Unclear pattern (variance=${variance.toFixed(4)}, delta=${delta.toFixed(3)})`,
+            recommended_action: "pivot",
+        });
+    }
+    /**
+     * Compute the decay_factor for the dissatisfaction drive score.
+     * - Stalled: 0.6
+     * - Recently recovered: follows a schedule (0.75 → 0.90 → 1.0)
+     * - Normal (not stalled, no recovery): 1.0
+     */
+    computeDecayFactor(isStalled, loopsSinceRecovery) {
+        if (isStalled) {
+            return DECAY_FACTOR_STALLED;
+        }
+        if (loopsSinceRecovery === null) {
+            // Not stalled, no recent recovery
+            return 1.0;
+        }
+        // Recovery schedule: find the highest threshold that has been reached
+        let factor = 1.0;
+        for (const { loops, factor: scheduledFactor } of RECOVERY_SCHEDULE) {
+            if (loopsSinceRecovery >= loops) {
+                factor = scheduledFactor;
+            }
+        }
+        return factor;
+    }
+    /**
+     * Returns true if the plateau_until date is in the future (stall detection suppressed).
+     */
+    isSuppressed(plateauUntil) {
+        if (plateauUntil === null) {
+            return false;
+        }
+        const until = new Date(plateauUntil);
+        const now = new Date();
+        return now < until;
+    }
+    /**
+     * Load the StallState for a goal from StateManager.
+     * Returns a default state if not found.
+     */
+    async getStallState(goalId) {
+        const raw = await this.stateManager.readRaw(`stalls/${goalId}.json`);
+        if (raw === null) {
+            return StallStateSchema.parse({
+                goal_id: goalId,
+                dimension_escalation: {},
+                global_escalation: 0,
+                decay_factors: {},
+                recovery_loops: {},
+            });
+        }
+        return StallStateSchema.parse(raw);
+    }
+    /**
+     * Persist the StallState for a goal via StateManager.
+     */
+    async saveStallState(goalId, state) {
+        const parsed = StallStateSchema.parse(state);
+        await this.stateManager.writeRaw(`stalls/${goalId}.json`, parsed);
+    }
+    /**
+     * Get the current escalation level for a dimension (default: 0).
+     */
+    async getEscalationLevel(goalId, dimensionName) {
+        const state = await this.getStallState(goalId);
+        return state.dimension_escalation[dimensionName] ?? 0;
+    }
+    /**
+     * Increment the escalation level for a dimension (cap at ESCALATION_CAP).
+     * Persists and returns the new level.
+     */
+    async incrementEscalation(goalId, dimensionName) {
+        const state = await this.getStallState(goalId);
+        const current = state.dimension_escalation[dimensionName] ?? 0;
+        const next = Math.min(current + 1, ESCALATION_CAP);
+        state.dimension_escalation[dimensionName] = next;
+        await this.saveStallState(goalId, state);
+        return next;
+    }
+    /**
+     * Reset the escalation level for a dimension to 0 and persist.
+     */
+    async resetEscalation(goalId, dimensionName) {
+        const state = await this.getStallState(goalId);
+        state.dimension_escalation[dimensionName] = 0;
+        await this.saveStallState(goalId, state);
+    }
+    // ─── Private Helpers ───
+    /**
+     * Compute the time threshold in hours for a task.
+     */
+    computeTimeThreshold(estimatedDuration, taskCategory) {
+        if (estimatedDuration) {
+            const estimatedHours = this.durationToHours(estimatedDuration);
+            return estimatedHours * 2;
+        }
+        if (taskCategory) {
+            const defaultHours = DEFAULT_DURATION_HOURS_BY_CATEGORY[taskCategory];
+            if (defaultHours !== undefined) {
+                return defaultHours;
+            }
+        }
+        return DEFAULT_DURATION_HOURS_FALLBACK;
+    }
+    /**
+     * Convert a duration object to hours.
+     */
+    durationToHours(duration) {
+        switch (duration.unit) {
+            case "minutes":
+                return duration.value / 60;
+            case "hours":
+                return duration.value;
+            case "days":
+                return duration.value * 24;
+            case "weeks":
+                return duration.value * 24 * 7;
+            default:
+                return duration.value; // assume hours as fallback
+        }
+    }
+}
+//# sourceMappingURL=stall-detector.js.map

package/dist/drive/stall-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stall-detector.js","sourceRoot":"","sources":["../../src/drive/stall-detector.ts"],"names":[],"mappings":"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"}

package/dist/drive-scorer.d.ts

@@ -0,0 +1,96 @@
+import type { DissatisfactionScore, DeadlineScore, OpportunityScore, DriveScore, DriveConfig, DriveContext } from "./types/drive.js";
+import type { GapVector } from "./types/gap.js";
+/**
+ * Score the dissatisfaction drive for a single dimension.
+ *
+ * Formula from drive-scoring.md section 1:
+ *   decay_factor(t) = decay_floor + (1 - decay_floor) × (1 - exp(-t / recovery_time))
+ *   score = normalized_weighted_gap × decay_factor
+ *
+ * At t=0: decay_factor = decay_floor (floor, not zero)
+ * At t→∞: decay_factor → 1.0 (full weight recovered)
+ *
+ * @param normalizedWeightedGap - pipeline output from GapCalculator [0, 1+]
+ * @param timeSinceLastAttemptHours - hours elapsed since last attempt (>= 0)
+ * @param config - optional drive configuration
+ */
+export declare function scoreDissatisfaction(normalizedWeightedGap: number, timeSinceLastAttemptHours: number, config?: DriveConfig): DissatisfactionScore;
+/**
+ * Score the deadline drive for a single dimension.
+ *
+ * Formula from drive-scoring.md section 2:
+ *   urgency(T) = exp(urgency_steepness × (1 - T / deadline_horizon))
+ *   score = normalized_weighted_gap × urgency
+ *
+ * Special cases:
+ *   T >= deadline_horizon → urgency = 1.0
+ *   T < 0 (overdue)       → score = cap (urgency at T=0)
+ *   deadline = null        → score = 0, urgency = 0
+ *
+ * @param normalizedWeightedGap - pipeline output from GapCalculator [0, 1+]
+ * @param timeRemainingHours - hours until deadline; null if no deadline; negative if overdue
+ * @param config - optional drive configuration
+ */
+export declare function scoreDeadline(normalizedWeightedGap: number, timeRemainingHours: number | null, config?: DriveConfig): DeadlineScore;
+/**
+ * Score the opportunity drive for a single dimension.
+ *
+ * Formula from drive-scoring.md section 3:
+ *   freshness_decay(t) = exp(-ln(2) × t / half_life)
+ *   score = opportunity_value × freshness_decay
+ *
+ * @param opportunityValue - computed opportunity value [0.0, 2.0]
+ * @param timeSinceDetectedHours - hours elapsed since opportunity was detected
+ * @param config - optional drive configuration
+ */
+export declare function scoreOpportunity(opportunityValue: number, timeSinceDetectedHours: number, config?: DriveConfig): OpportunityScore;
+/**
+ * Compute the opportunity value from its components.
+ *
+ * Formula from drive-scoring.md section 3:
+ *   value = downstream_impact × (1 + external_bonus + timing_bonus)
+ *
+ * @param downstreamImpact - fraction of dimensions that depend on this one [0.0, 1.0]
+ * @param externalBonus - bonus from event queue (0.0 | 0.25 | 0.5)
+ * @param timingBonus - bonus from LLM evaluation (0.0 | 0.25 | 0.5)
+ * @returns opportunity value in [0.0, 2.0]
+ */
+export declare function computeOpportunityValue(downstreamImpact: number, externalBonus: number, timingBonus: number): number;
+/**
+ * Combine the three drive scores into a final DriveScore.
+ *
+ * Formula from drive-scoring.md:
+ *   final_score = max(dissatisfaction.score, deadline.score, opportunity.score)
+ *   dominant_drive = whichever drive had the max score
+ *
+ * Override: if deadline.urgency >= urgency_override_threshold:
+ *   final_score = deadline.score
+ *   dominant_drive = "deadline"
+ *
+ * @param dissatisfaction - result from scoreDissatisfaction
+ * @param deadline - result from scoreDeadline
+ * @param opportunity - result from scoreOpportunity
+ * @param config - optional drive configuration
+ */
+export declare function combineDriveScores(dissatisfaction: DissatisfactionScore, deadline: DeadlineScore, opportunity: OpportunityScore, config?: DriveConfig): DriveScore;
+/**
+ * Score all dimensions in a GapVector using the provided context.
+ *
+ * For each dimension in gapVector.gaps:
+ *   1. Retrieve context (timeSinceLastAttempt, deadline, opportunity)
+ *   2. Compute all three drive scores
+ *   3. Combine into a DriveScore
+ *
+ * @param gapVector - output from GapCalculator.calculateGapVector
+ * @param context - per-dimension context (timings, deadlines, opportunities)
+ * @param config - optional drive configuration
+ */
+export declare function scoreAllDimensions(gapVector: GapVector, context: DriveContext, config?: DriveConfig): DriveScore[];
+/**
+ * Sort DriveScore array by final_score descending (highest priority first).
+ *
+ * @param scores - array of DriveScore objects
+ * @returns new array sorted by final_score descending
+ */
+export declare function rankDimensions(scores: DriveScore[]): DriveScore[];
+//# sourceMappingURL=drive-scorer.d.ts.map

package/dist/drive-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-scorer.d.ts","sourceRoot":"","sources":["../src/drive-scorer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AA4BhD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,qBAAqB,EAAE,MAAM,EAC7B,yBAAyB,EAAE,MAAM,EACjC,MAAM,CAAC,EAAE,WAAW,GACnB,oBAAoB,CAgBtB;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,qBAAqB,EAAE,MAAM,EAC7B,kBAAkB,EAAE,MAAM,GAAG,IAAI,EACjC,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAqCf;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,MAAM,EACxB,sBAAsB,EAAE,MAAM,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,gBAAgB,CAclB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,oBAAoB,EACrC,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,gBAAgB,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,UAAU,CAsCZ;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,YAAY,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,UAAU,EAAE,CA6Bd;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAEjE"}