conatus 0.1.0

package/dist/drive/satisficing-propagation.js

@@ -0,0 +1,196 @@
+import { aggregateValues, getSatisfiedValue } from "./satisficing-helpers.js";
+/**
+ * Judge completion of an entire goal tree by checking all children recursively.
+ * Non-leaf nodes are complete when all children are completed or cancelled(merged).
+ *
+ * @param rootId The ID of the root goal of the tree.
+ * @param stateManager StateManager instance for loading goals.
+ * @param isGoalComplete Function to check leaf node completion.
+ * @returns CompletionJudgment for the root node.
+ */
+export async function judgeTreeCompletion(rootId, stateManager, isGoalComplete, convergenceStatuses) {
+    const goal = await stateManager.loadGoal(rootId);
+    if (goal === null) {
+        return {
+            is_complete: false,
+            blocking_dimensions: [],
+            low_confidence_dimensions: [],
+            needs_verification_task: false,
+            checked_at: new Date().toISOString(),
+        };
+    }
+    // Leaf node (no children): delegate to existing isGoalComplete
+    if (!goal.children_ids || goal.children_ids.length === 0) {
+        return isGoalComplete(goal, convergenceStatuses);
+    }
+    // Non-leaf node: check all children recursively
+    const blockingDimensions = [];
+    const lowConfidenceDimensions = [];
+    let needsVerification = false;
+    for (const childId of goal.children_ids) {
+        const child = await stateManager.loadGoal(childId);
+        // Missing child is treated as blocking
+        if (child === null) {
+            blockingDimensions.push(childId);
+            continue;
+        }
+        // Cancelled children count as complete (covers "merged" prune reason)
+        if (child.status === "cancelled") {
+            continue;
+        }
+        // Recurse into child
+        const childJudgment = await judgeTreeCompletion(childId, stateManager, isGoalComplete, convergenceStatuses);
+        if (!childJudgment.is_complete) {
+            // Aggregate child's blocking and low-confidence dimensions
+            for (const dim of childJudgment.blocking_dimensions) {
+                if (!blockingDimensions.includes(dim)) {
+                    blockingDimensions.push(dim);
+                }
+            }
+            for (const dim of childJudgment.low_confidence_dimensions) {
+                if (!lowConfidenceDimensions.includes(dim)) {
+                    lowConfidenceDimensions.push(dim);
+                }
+            }
+        }
+        if (childJudgment.needs_verification_task) {
+            needsVerification = true;
+        }
+    }
+    const isComplete = blockingDimensions.length === 0 && lowConfidenceDimensions.length === 0;
+    return {
+        is_complete: isComplete,
+        blocking_dimensions: blockingDimensions,
+        low_confidence_dimensions: lowConfidenceDimensions,
+        needs_verification_task: needsVerification,
+        checked_at: new Date().toISOString(),
+    };
+}
+/**
+ * Propagate subgoal completion to the parent goal's matching dimension.
+ *
+ * Phase 2: supports dimension_mapping for aggregation-based propagation.
+ * - If any subgoal dimension has dimension_mapping set, use aggregation path.
+ * - Mixed: mapped dimensions use aggregation; unmapped dimensions fall back to name matching.
+ * - Backwards compatible: if no dimensions have dimension_mapping, behaves like MVP.
+ *
+ * @param subgoalId The subgoal's ID (used for name matching in MVP path).
+ * @param parentGoalId The parent goal's ID to update.
+ * @param stateManager StateManager instance.
+ * @param computeActualProgress Function to compute progress for a dimension.
+ * @param subgoalDimensions Optional subgoal dimensions for aggregation mapping.
+ */
+export async function propagateSubgoalCompletion(subgoalId, parentGoalId, stateManager, computeActualProgress, subgoalDimensions, logger) {
+    const parentGoal = await stateManager.loadGoal(parentGoalId);
+    if (parentGoal === null) {
+        throw new Error(`propagateSubgoalCompletion: parent goal "${parentGoalId}" not found`);
+    }
+    const now = new Date().toISOString();
+    // Phase 2: if subgoalDimensions are provided and any has dimension_mapping, use aggregation path
+    if (subgoalDimensions && subgoalDimensions.length > 0) {
+        const mappedDims = subgoalDimensions.filter((d) => d.dimension_mapping !== null);
+        const unmappedDims = subgoalDimensions.filter((d) => d.dimension_mapping === null);
+        // Process mapped dimensions: group by parent_dimension
+        const parentDimUpdates = new Map();
+        if (mappedDims.length > 0) {
+            // Group subgoal dimensions by target parent_dimension
+            const grouped = new Map();
+            for (const dim of mappedDims) {
+                // dimension_mapping is non-null: mappedDims is filtered to only include dims with non-null mapping
+                const mapping = dim.dimension_mapping ?? { parent_dimension: "", aggregation: "average" };
+                const existing = grouped.get(mapping.parent_dimension) ?? [];
+                existing.push(dim);
+                grouped.set(mapping.parent_dimension, existing);
+            }
+            // Compute aggregated value for each parent dimension
+            for (const [parentDimName, dims] of grouped) {
+                // dims is non-empty (grouped entries are only created when pushing to them above)
+                // dimension_mapping is non-null for all dims in this group (filtered by mappedDims)
+                const firstDim = dims[0];
+                const aggregation = firstDim?.dimension_mapping?.aggregation ?? "avg";
+                const numericValues = [];
+                const fulfillmentRatios = [];
+                for (const dim of dims) {
+                    const cv = dim.current_value;
+                    if (typeof cv === "number") {
+                        numericValues.push(cv);
+                    }
+                    else if (typeof cv === "boolean") {
+                        numericValues.push(cv ? 1 : 0);
+                    }
+                    else if (typeof cv === "string") {
+                        const parsed = Number(cv);
+                        if (!isNaN(parsed)) {
+                            numericValues.push(parsed);
+                        }
+                        else {
+                            // Non-numeric in avg mode: skip with warning
+                            if (aggregation === "avg") {
+                                logger?.warn(`propagateSubgoalCompletion: skipping non-numeric current_value "${cv}" for dimension "${dim.name}" in avg aggregation`);
+                            }
+                        }
+                    }
+                    // For all_required: also compute fulfillment ratio
+                    if (aggregation === "all_required") {
+                        const progress = computeActualProgress(dim);
+                        fulfillmentRatios.push(progress);
+                    }
+                }
+                const thresholds = dims.map((d) => {
+                    const th = d.threshold;
+                    if (th.type === "min")
+                        return th.value;
+                    if (th.type === "max")
+                        return th.value;
+                    if (th.type === "range")
+                        return th.high;
+                    return 1;
+                });
+                const aggregated = aggregation === "all_required"
+                    ? aggregateValues(fulfillmentRatios, aggregation, thresholds)
+                    : aggregateValues(numericValues, aggregation, thresholds);
+                parentDimUpdates.set(parentDimName, aggregated);
+            }
+        }
+        // Build updated dimensions array for the parent goal
+        let updatedDimensions = parentGoal.dimensions.map((d) => {
+            if (parentDimUpdates.has(d.name)) {
+                return { ...d, current_value: parentDimUpdates.get(d.name), last_updated: now };
+            }
+            return d;
+        });
+        // Process unmapped dimensions: fall back to name-based matching (MVP path)
+        for (const unmappedDim of unmappedDims) {
+            const matchedIndex = updatedDimensions.findIndex((d) => d.name === unmappedDim.name || d.name.includes(unmappedDim.name));
+            if (matchedIndex !== -1) {
+                const matchedDim = updatedDimensions[matchedIndex];
+                const satisfiedValue = getSatisfiedValue(matchedDim);
+                updatedDimensions = updatedDimensions.map((d, i) => i === matchedIndex ? { ...d, current_value: satisfiedValue, last_updated: now } : d);
+            }
+        }
+        await stateManager.saveGoal({
+            ...parentGoal,
+            dimensions: updatedDimensions,
+            updated_at: now,
+        });
+        return;
+    }
+    // MVP path: name-based matching (backwards compatible)
+    const matchedDimIndex = parentGoal.dimensions.findIndex((d) => d.name === subgoalId || d.name.includes(subgoalId));
+    if (matchedDimIndex === -1) {
+        // No matching dimension — nothing to propagate
+        return;
+    }
+    const matchedDim = parentGoal.dimensions[matchedDimIndex];
+    // Set current_value to threshold value so isDimensionSatisfied returns true
+    const satisfiedValue = getSatisfiedValue(matchedDim);
+    const updatedDimensions = parentGoal.dimensions.map((d, i) => i === matchedDimIndex
+        ? { ...d, current_value: satisfiedValue, last_updated: now }
+        : d);
+    await stateManager.saveGoal({
+        ...parentGoal,
+        dimensions: updatedDimensions,
+        updated_at: now,
+    });
+}
+//# sourceMappingURL=satisficing-propagation.js.map

package/dist/drive/satisficing-propagation.js.map

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

package/dist/drive/stall-detector.d.ts

@@ -0,0 +1,113 @@
+import { StateManager } from "../state-manager.js";
+import type { StallReport, StallState, StallAnalysis } from "../types/stall.js";
+import type { CharacterConfig } from "../types/character.js";
+/**
+ * StallDetector detects stalls (circuit breaker) in the Motiva orchestrator loop.
+ * Supports 4 stall types: dimension_stall, time_exceeded, consecutive_failure, global_stall.
+ */
+export declare class StallDetector {
+    private readonly stateManager;
+    private readonly characterConfig;
+    constructor(stateManager: StateManager, characterConfig?: CharacterConfig);
+    /**
+     * 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)
+     */
+    private getAdjustedN;
+    /**
+     * 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: string, dimensionName: string, gapHistory: Array<{
+        normalized_gap: number;
+    }>, feedbackCategory?: string): StallReport | null;
+    /**
+     * Check if a task has exceeded its time threshold (estimate × 2, or default by category).
+     */
+    checkTimeExceeded(task: {
+        task_id?: string;
+        goal_id: string;
+        estimated_duration?: {
+            value: number;
+            unit: string;
+        } | null;
+        started_at?: string | null;
+        task_category?: string;
+    }): StallReport | null;
+    /**
+     * Check if a dimension has had 3+ consecutive failures.
+     */
+    checkConsecutiveFailures(goalId: string, dimensionName: string, consecutiveFailureCount: number): StallReport | null;
+    /**
+     * Check if ALL dimensions show no improvement for loopThreshold loops.
+     * Returns null if any dimension improved.
+     */
+    checkGlobalStall(goalId: string, allDimensionGaps: Map<string, Array<{
+        normalized_gap: number;
+    }>>, loopThreshold?: number): StallReport | null;
+    /**
+     * Classify the root cause of a stall based on stall type and goal context.
+     */
+    classifyStallCause(stallType: string, goal: {
+        dimensions?: Array<{
+            confidence?: number;
+        }>;
+    }): string;
+    /**
+     * 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: Array<{
+        normalized_gap: number;
+    }>): StallAnalysis;
+    /**
+     * 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: boolean, loopsSinceRecovery: number | null): number;
+    /**
+     * Returns true if the plateau_until date is in the future (stall detection suppressed).
+     */
+    isSuppressed(plateauUntil: string | null): boolean;
+    /**
+     * Load the StallState for a goal from StateManager.
+     * Returns a default state if not found.
+     */
+    getStallState(goalId: string): Promise<StallState>;
+    /**
+     * Persist the StallState for a goal via StateManager.
+     */
+    saveStallState(goalId: string, state: StallState): Promise<void>;
+    /**
+     * Get the current escalation level for a dimension (default: 0).
+     */
+    getEscalationLevel(goalId: string, dimensionName: string): Promise<number>;
+    /**
+     * Increment the escalation level for a dimension (cap at ESCALATION_CAP).
+     * Persists and returns the new level.
+     */
+    incrementEscalation(goalId: string, dimensionName: string): Promise<number>;
+    /**
+     * Reset the escalation level for a dimension to 0 and persist.
+     */
+    resetEscalation(goalId: string, dimensionName: string): Promise<void>;
+    /**
+     * Compute the time threshold in hours for a task.
+     */
+    private computeTimeThreshold;
+    /**
+     * Convert a duration object to hours.
+     */
+    private durationToHours;
+}
+//# sourceMappingURL=stall-detector.d.ts.map

package/dist/drive/stall-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stall-detector.d.ts","sourceRoot":"","sources":["../../src/drive/stall-detector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA0C7D;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAEtC,YAAY,EAAE,YAAY,EAAE,eAAe,CAAC,EAAE,eAAe;IAKzE;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAUpB;;;OAGG;IACH,mBAAmB,CACjB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,EAC7C,gBAAgB,CAAC,EAAE,MAAM,GACxB,WAAW,GAAG,IAAI;IA8BrB;;OAEG;IACH,iBAAiB,CAAC,IAAI,EAAE;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QAC5D,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,WAAW,GAAG,IAAI;IA4BtB;;OAEG;IACH,wBAAwB,CACtB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,uBAAuB,EAAE,MAAM,GAC9B,WAAW,GAAG,IAAI;IAiBrB;;;OAGG;IACH,gBAAgB,CACd,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,EAChE,aAAa,SAAsB,GAClC,WAAW,GAAG,IAAI;IAkCrB;;OAEG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;QAAE,UAAU,CAAC,EAAE,KAAK,CAAC;YAAE,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GACpD,MAAM;IA4BT;;;;;;;;;OASG;IACH,iBAAiB,CAAC,UAAU,EAAE,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,aAAa;IA8E/E;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAqBjF;;OAEG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAUlD;;;OAGG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAexD;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtE;;OAEG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKhF;;;OAGG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASjF;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3E;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;OAEG;IACH,OAAO,CAAC,eAAe;CAcxB"}