pulseed 0.4.18 → 0.4.20

package/dist/platform/drive/drive-scorer.js

@@ -0,0 +1,243 @@
+import { DriveConfigSchema } from "../../base/types/drive.js";
+/**
+ * DriveScorer implements the three-drive scoring pipeline defined in drive-scoring.md:
+ *   Dissatisfaction Drive × Deadline Drive × Opportunity Drive → combined DriveScore
+ *
+ * All functions are pure (no side effects).
+ *
+ * Key design constraints:
+ * - Input is normalized_weighted_gap from GapCalculator pipeline ([0, 1]).
+ * - Final score = max(dissatisfaction, deadline, opportunity).
+ * - Deadline urgency override kicks in when urgency >= urgency_override_threshold.
+ */
+// ─── Default Config ───
+function defaultConfig() {
+    return DriveConfigSchema.parse({});
+}
+// ─── Helpers ───
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+// ─── Dissatisfaction Drive ───
+/**
+ * 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 function scoreDissatisfaction(normalizedWeightedGap, timeSinceLastAttemptHours, config) {
+    const cfg = config ?? defaultConfig();
+    const { decay_floor, recovery_time_hours } = cfg;
+    const t = Math.max(0, timeSinceLastAttemptHours);
+    const decayFactor = decay_floor + (1 - decay_floor) * (1 - Math.exp(-t / recovery_time_hours));
+    const score = normalizedWeightedGap * decayFactor;
+    return {
+        dimension_name: "",
+        normalized_weighted_gap: normalizedWeightedGap,
+        decay_factor: decayFactor,
+        score,
+    };
+}
+// ─── Deadline Drive ───
+/**
+ * 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 function scoreDeadline(normalizedWeightedGap, timeRemainingHours, config, pacingRatio) {
+    const cfg = config ?? defaultConfig();
+    const { deadline_horizon_hours, urgency_steepness } = cfg;
+    if (timeRemainingHours === null) {
+        return {
+            dimension_name: "",
+            normalized_weighted_gap: normalizedWeightedGap,
+            urgency: 0,
+            score: 0,
+        };
+    }
+    // Cap value: urgency at T=0 (moment of deadline)
+    const urgencyAtZero = Math.exp(urgency_steepness * (1 - 0 / deadline_horizon_hours));
+    let urgency;
+    if (timeRemainingHours >= deadline_horizon_hours) {
+        // Far from deadline — urgency is at its minimum (1.0 by formula at T=horizon)
+        urgency = 1.0;
+    }
+    else if (timeRemainingHours < 0) {
+        // Overdue: cap at urgency computed at T=0
+        urgency = urgencyAtZero;
+    }
+    else {
+        urgency = Math.exp(urgency_steepness * (1 - timeRemainingHours / deadline_horizon_hours));
+    }
+    const pacingBonus = pacingRatio != null
+        ? Math.max(0, pacingRatio - 1.0) * cfg.pacing_urgency_weight
+        : 0;
+    const score = normalizedWeightedGap * (urgency + pacingBonus);
+    return {
+        dimension_name: "",
+        normalized_weighted_gap: normalizedWeightedGap,
+        urgency,
+        score,
+    };
+}
+// ─── Opportunity Drive ───
+/**
+ * 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 function scoreOpportunity(opportunityValue, timeSinceDetectedHours, config) {
+    const cfg = config ?? defaultConfig();
+    const { half_life_hours } = cfg;
+    const t = Math.max(0, timeSinceDetectedHours);
+    const freshnessDecay = Math.exp((-Math.LN2 * t) / half_life_hours);
+    const score = opportunityValue * freshnessDecay;
+    return {
+        dimension_name: "",
+        opportunity_value: opportunityValue,
+        freshness_decay: freshnessDecay,
+        score,
+    };
+}
+// ─── Opportunity Value Computation ───
+/**
+ * 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 function computeOpportunityValue(downstreamImpact, externalBonus, timingBonus) {
+    return downstreamImpact * (1 + externalBonus + timingBonus);
+}
+// ─── Score Combination ───
+/**
+ * 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 function combineDriveScores(dissatisfaction, deadline, opportunity, config) {
+    const cfg = config ?? defaultConfig();
+    const { urgency_override_threshold } = cfg;
+    // Deadline urgency override takes precedence
+    if (deadline.urgency >= urgency_override_threshold) {
+        return {
+            dimension_name: dissatisfaction.dimension_name,
+            dissatisfaction: dissatisfaction.score,
+            deadline: deadline.score,
+            opportunity: opportunity.score,
+            final_score: deadline.score,
+            dominant_drive: "deadline",
+        };
+    }
+    // Normal case: max of the three scores
+    const scores = [
+        { drive: "dissatisfaction", value: dissatisfaction.score },
+        { drive: "deadline", value: deadline.score },
+        { drive: "opportunity", value: opportunity.score },
+    ];
+    let best = scores[0];
+    for (const s of scores) {
+        if (s.value > best.value) {
+            best = s;
+        }
+    }
+    return {
+        dimension_name: dissatisfaction.dimension_name,
+        dissatisfaction: dissatisfaction.score,
+        deadline: deadline.score,
+        opportunity: opportunity.score,
+        final_score: best.value,
+        dominant_drive: best.drive,
+    };
+}
+// ─── All Dimensions ───
+/**
+ * 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 function scoreAllDimensions(gapVector, context, config) {
+    return gapVector.gaps.map((weightedGap) => {
+        const dimName = weightedGap.dimension_name;
+        const nwg = weightedGap.normalized_weighted_gap;
+        const timeSince = context.time_since_last_attempt[dimName] ?? 0;
+        const deadline = context.deadlines[dimName] !== undefined
+            ? context.deadlines[dimName]
+            : null;
+        const opp = context.opportunities[dimName];
+        const dissatisfactionRaw = scoreDissatisfaction(nwg, timeSince, config);
+        const deadlineRaw = scoreDeadline(nwg, deadline, config, context.pacing[dimName]?.pacingRatio);
+        const opportunityRaw = opp !== null && opp !== undefined
+            ? (() => {
+                const timeSinceDetected = (Date.now() - new Date(opp.detected_at).getTime()) / (1000 * 60 * 60);
+                return scoreOpportunity(opp.value, timeSinceDetected, config);
+            })()
+            : scoreOpportunity(0, 0, config);
+        const combined = combineDriveScores(dissatisfactionRaw, deadlineRaw, opportunityRaw, config);
+        return { ...combined, dimension_name: dimName };
+    });
+}
+// ─── Ranking ───
+/**
+ * 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 function rankDimensions(scores) {
+    return [...scores].sort((a, b) => {
+        const scoreDiff = b.final_score - a.final_score;
+        if (scoreDiff !== 0)
+            return scoreDiff;
+        return a.dimension_name < b.dimension_name ? -1 : a.dimension_name > b.dimension_name ? 1 : 0;
+    });
+}
+//# sourceMappingURL=drive-scorer.js.map

package/dist/platform/drive/drive-scorer.js.map

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

package/dist/platform/drive/drive-system.d.ts

@@ -0,0 +1,107 @@
+import type { PulSeedEvent, GoalSchedule } from "../../base/types/drive.js";
+import type { StateManager } from "../../base/state/state-manager.js";
+import type { Logger } from "../../runtime/logger.js";
+export interface GoalActivationSnapshot {
+    goalId: string;
+    shouldActivate: boolean;
+    schedule: GoalSchedule | null;
+}
+/**
+ * DriveSystem handles lightweight activation checks (no LLM calls), event queue
+ * processing, and goal schedule management.
+ *
+ * File layout:
+ *   <baseDir>/events/*.json          — event queue
+ *   <baseDir>/events/archive/*.json  — processed events
+ *   <baseDir>/schedule/<goalId>.json — goal schedules
+ *
+ * Inactive goal statuses: "completed", "cancelled", "archived"
+ * All writes are atomic: write to .tmp file, then rename.
+ */
+export declare class DriveSystem {
+    private readonly baseDir;
+    private readonly stateManager;
+    private readonly logger?;
+    private watcher;
+    private inMemoryQueue;
+    private onEventCallback;
+    private readonly initPromise;
+    constructor(stateManager: StateManager, options?: {
+        baseDir?: string;
+        logger?: Logger;
+    });
+    private ensureDirectories;
+    private isTerminalGoalStatus;
+    private isScheduleDueForSnapshot;
+    getGoalActivationSnapshot(goalId: string): Promise<GoalActivationSnapshot>;
+    /**
+     * Lightweight check (no LLM). Returns true if any condition is met:
+     * 1. Event queue has unprocessed events for this goal
+     * 2. Schedule is due (next_check_at <= now)
+     * 3. Goal is not in a terminal status ("completed", "cancelled", "archived")
+     */
+    shouldActivate(goalId: string): Promise<boolean>;
+    /**
+     * Read all JSON files from {baseDir}/events/ directory.
+     * Parse each as PulSeedEvent. Return sorted by timestamp (oldest first).
+     * Skips files that fail to parse (logs a warning).
+     */
+    readEventQueue(): Promise<PulSeedEvent[]>;
+    /**
+     * Move an event file from {baseDir}/events/{fileName} to
+     * {baseDir}/events/archive/{fileName}. Creates the archive dir if needed.
+     */
+    archiveEvent(eventFileName: string): Promise<void>;
+    /**
+     * Read queue, archive each processed event, return the events.
+     */
+    processEvents(): Promise<PulSeedEvent[]>;
+    /**
+     * Load schedule from {baseDir}/schedule/{goalId}.json.
+     * Returns null if no schedule exists or parsing fails.
+     */
+    getSchedule(goalId: string): Promise<GoalSchedule | null>;
+    /**
+     * Save schedule atomically to {baseDir}/schedule/{goalId}.json.
+     */
+    updateSchedule(goalId: string, schedule: GoalSchedule): Promise<void>;
+    /**
+     * Check if the schedule for a goal is due (next_check_at <= now).
+     * If no schedule exists, returns true (needs initial check).
+     */
+    isScheduleDue(goalId: string): Promise<boolean>;
+    /**
+     * Create a new schedule with next_check_at = now + intervalHours.
+     */
+    createDefaultSchedule(goalId: string, intervalHours: number): GoalSchedule;
+    /**
+     * Sort goals by drive score (highest first).
+     * Goals without scores go last (in their original relative order).
+     */
+    prioritizeGoals(goalIds: string[], scores: Map<string, number>): string[];
+    /**
+     * Write an event file to the events directory.
+     * Public method used by EventServer to enqueue events via HTTP.
+     */
+    writeEvent(event: PulSeedEvent): Promise<void>;
+    /**
+     * Start watching the events directory for new event files.
+     * When a new .json file appears, parse it and push it to the in-memory queue.
+     * Optionally calls onEvent callback immediately on each new event.
+     */
+    startWatcher(onEvent?: (event: PulSeedEvent) => void): void;
+    /**
+     * Handle a file event from the watcher asynchronously.
+     */
+    private handleWatchEvent;
+    /**
+     * Stop watching the events directory and clear the callback.
+     */
+    stopWatcher(): void;
+    /**
+     * Return all events accumulated in the in-memory queue since the last drain,
+     * and clear the queue.
+     */
+    drainInMemoryQueue(): PulSeedEvent[];
+}
+//# sourceMappingURL=drive-system.d.ts.map

package/dist/platform/drive/drive-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-system.d.ts","sourceRoot":"","sources":["../../../src/platform/drive/drive-system.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,eAAe,CAAgD;IACvE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;gBAEhC,YAAY,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;YAczE,iBAAiB;IAa/B,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,wBAAwB;IAO1B,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAiChF;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtD;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IA2C/C;;;OAGG;IACG,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IA6C9C;;;OAGG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAyB/D;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAS3E;;;OAGG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASrD;;OAEG;IACH,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,YAAY;IAgB1E;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE;IAqBzE;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD;;;;OAIG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IAsB3D;;OAEG;YACW,gBAAgB;IAoB9B;;OAEG;IACH,WAAW,IAAI,IAAI;IAQnB;;;OAGG;IACH,kBAAkB,IAAI,YAAY,EAAE;CAKrC"}