conatus 0.1.0

package/dist/portfolio-rebalance.js

@@ -0,0 +1,254 @@
+/**
+ * portfolio-rebalance.ts
+ *
+ * Pure/stateless helpers for PortfolioManager rebalancing logic.
+ * Functions here take configuration and data as explicit parameters
+ * and return results without side effects (except via the provided
+ * callbacks).
+ */
+/**
+ * Get the current gap value for a specific dimension of a goal.
+ * Reads from gap data provided by the caller (StateManager.readRaw).
+ */
+export async function getCurrentGapForDimension(goalId, dimension, readRaw) {
+    const raw = await readRaw(`gaps/${goalId}/current.json`);
+    if (!raw || typeof raw !== "object")
+        return null;
+    const gaps = raw;
+    const dimensionGap = gaps[dimension];
+    if (typeof dimensionGap === "number")
+        return dimensionGap;
+    const dimensions = gaps["dimensions"];
+    if (dimensions && typeof dimensions === "object") {
+        const dimData = dimensions[dimension];
+        if (dimData && typeof dimData === "object") {
+            const nwg = dimData["normalized_weighted_gap"];
+            if (typeof nwg === "number")
+                return nwg;
+        }
+    }
+    return null;
+}
+/**
+ * Calculate gap delta attributed to a strategy using dimension-target matching.
+ * Sums gap improvements across the strategy's target_dimensions.
+ */
+export async function calculateGapDeltaForStrategy(strategy, goalId, readRaw) {
+    let totalDelta = 0;
+    for (const dimension of strategy.target_dimensions) {
+        const currentGap = await getCurrentGapForDimension(goalId, dimension, readRaw);
+        if (currentGap === null)
+            continue;
+        const baseline = strategy.gap_snapshot_at_start ?? 1.0;
+        const delta = baseline - currentGap;
+        totalDelta += delta;
+    }
+    return totalDelta;
+}
+/**
+ * Calculate initial equal-split allocations for N strategies.
+ * Single strategy: [1.0].
+ * Multiple: equal split clamped to [min_allocation, max_allocation], sum = 1.0.
+ */
+export function calculateInitialAllocations(count, config) {
+    if (count === 1)
+        return [1.0];
+    const { min_allocation, max_allocation } = config;
+    let base = 1.0 / count;
+    base = Math.max(min_allocation, Math.min(max_allocation, base));
+    const allocations = new Array(count).fill(base);
+    const sum = allocations.reduce((a, b) => a + b, 0);
+    if (sum > 0 && Math.abs(sum - 1.0) > 0.001) {
+        const factor = 1.0 / sum;
+        for (let i = 0; i < allocations.length; i++) {
+            allocations[i] = Math.max(min_allocation, Math.min(max_allocation, allocations[i] * factor));
+        }
+        const finalSum = allocations.slice(0, -1).reduce((a, b) => a + b, 0);
+        allocations[allocations.length - 1] = Math.max(min_allocation, 1.0 - finalSum);
+    }
+    return allocations;
+}
+/**
+ * Count how many consecutive recent rebalances a strategy has been the lowest scorer
+ * (i.e., was adjusted down to min_allocation).
+ */
+export function countConsecutiveLowestRebalances(strategyId, history, minAllocation) {
+    let count = 0;
+    for (let i = history.length - 1; i >= 0; i--) {
+        const rebalance = history[i];
+        const adjustment = rebalance.adjustments.find((a) => a.strategy_id === strategyId);
+        if (adjustment && adjustment.new_allocation <= minAllocation) {
+            count++;
+        }
+        else {
+            break;
+        }
+    }
+    return count;
+}
+/**
+ * Redistribute freed allocation proportionally among remaining strategies
+ * based on effectiveness scores.
+ *
+ * Calls updateAllocation(goalId, strategyId, newAllocation) for each change.
+ */
+export function redistributeAllocation(goalId, remaining, records, freedAllocation, config, result, updateAllocation) {
+    if (remaining.length === 0 || freedAllocation <= 0)
+        return;
+    const scoredRemaining = remaining.map((s) => {
+        const record = records.find((r) => r.strategy_id === s.id);
+        return {
+            strategy: s,
+            score: record?.effectiveness_score ?? 0,
+        };
+    });
+    const totalScore = scoredRemaining.reduce((sum, r) => sum + Math.max(r.score, 0), 0);
+    for (const { strategy, score } of scoredRemaining) {
+        const proportion = totalScore > 0
+            ? Math.max(score, 0) / totalScore
+            : 1.0 / remaining.length;
+        const additionalAllocation = freedAllocation * proportion;
+        const oldAllocation = strategy.allocation;
+        const newAllocation = Math.min(config.max_allocation, oldAllocation + additionalAllocation);
+        if (Math.abs(newAllocation - oldAllocation) > 0.001) {
+            updateAllocation(goalId, strategy.id, newAllocation);
+            result.adjustments.push({
+                strategy_id: strategy.id,
+                old_allocation: oldAllocation,
+                new_allocation: newAllocation,
+                reason: "Redistribution from terminated strategy",
+            });
+        }
+    }
+}
+/**
+ * Adjust allocations based on effectiveness scores.
+ * Increases high-performers, decreases low-performers.
+ *
+ * Calls updateAllocation(goalId, strategyId, newAllocation) for each change.
+ */
+export function adjustAllocations(goalId, strategies, scoredRecords, config, result, updateAllocation) {
+    const sorted = [...scoredRecords].sort((a, b) => (b.effectiveness_score ?? 0) - (a.effectiveness_score ?? 0));
+    const totalScore = sorted.reduce((sum, r) => sum + Math.max(r.effectiveness_score ?? 0, 0), 0);
+    if (totalScore <= 0)
+        return;
+    const adjustments = [];
+    const newAllocations = new Map();
+    for (const record of sorted) {
+        const strategy = strategies.find((s) => s.id === record.strategy_id);
+        if (!strategy)
+            continue;
+        const proportion = Math.max(record.effectiveness_score ?? 0, 0) / totalScore;
+        let targetAllocation = proportion;
+        targetAllocation = Math.max(config.min_allocation, Math.min(config.max_allocation, targetAllocation));
+        newAllocations.set(strategy.id, targetAllocation);
+    }
+    const rawSum = Array.from(newAllocations.values()).reduce((a, b) => a + b, 0);
+    if (rawSum > 0 && Math.abs(rawSum - 1.0) > 0.001) {
+        const factor = 1.0 / rawSum;
+        for (const [id, alloc] of newAllocations) {
+            newAllocations.set(id, Math.max(config.min_allocation, alloc * factor));
+        }
+    }
+    for (const [strategyId, newAllocation] of newAllocations) {
+        const strategy = strategies.find((s) => s.id === strategyId);
+        if (!strategy)
+            continue;
+        const oldAllocation = strategy.allocation;
+        if (Math.abs(newAllocation - oldAllocation) > 0.001) {
+            updateAllocation(goalId, strategyId, newAllocation);
+            adjustments.push({
+                strategy_id: strategyId,
+                old_allocation: oldAllocation,
+                new_allocation: newAllocation,
+                reason: `Score-based rebalancing (effectiveness: ${scoredRecords
+                    .find((r) => r.strategy_id === strategyId)
+                    ?.effectiveness_score?.toFixed(3) ?? "N/A"})`,
+            });
+        }
+    }
+    result.adjustments.push(...adjustments);
+}
+/**
+ * Handle expiry of a WaitStrategy.
+ *
+ * When wait_until has passed:
+ * - Gap improved: return null
+ * - Gap unchanged: activate fallback strategy if one exists
+ * - Gap worsened: return rebalance trigger
+ *
+ * @param isWaitStrategy - predicate to detect WaitStrategy instances
+ * @param getGap - get current gap for a dimension of a goal
+ * @param updateState - transition a strategy to a new state
+ * @param getPortfolioStrategies - get all strategies for a goal
+ */
+export async function handleWaitStrategyExpiry(goalId, strategyId, strategy, isWaitStrategy, getGap, updateState, getPortfolioStrategies) {
+    if (!isWaitStrategy(strategy))
+        return null;
+    const waitStrategy = strategy;
+    const waitUntil = new Date(waitStrategy.wait_until).getTime();
+    const now = Date.now();
+    if (now < waitUntil)
+        return null;
+    const startGap = strategy.gap_snapshot_at_start;
+    if (startGap === null)
+        return null;
+    const currentGap = await getGap(goalId, strategy.primary_dimension);
+    if (currentGap === null)
+        return null;
+    const gapDelta = currentGap - startGap;
+    if (gapDelta < 0) {
+        return null;
+    }
+    if (gapDelta === 0) {
+        if (waitStrategy.fallback_strategy_id) {
+            const strategies = await getPortfolioStrategies(goalId);
+            const fallback = strategies.find((s) => s.id === waitStrategy.fallback_strategy_id);
+            if (fallback && fallback.state === "candidate") {
+                await updateState(fallback.id, "active");
+            }
+        }
+        return null;
+    }
+    return {
+        type: "stall_detected",
+        strategy_id: strategyId,
+        details: `WaitStrategy expired with gap worsening: ${startGap.toFixed(3)} → ${currentGap.toFixed(3)}`,
+    };
+}
+/**
+ * Select the next strategy across multiple goals.
+ *
+ * Sorts goals by "saturation ratio" (tasks dispatched / allocation) — the most
+ * underserved goal (lowest saturation) gets the next task. Within that goal,
+ * selectStrategyForTask() picks the best strategy.
+ *
+ * @param goalTaskCounts - map of goalId → total tasks dispatched
+ * @param selectStrategyForTask - select best strategy within one goal
+ */
+export async function selectNextStrategyAcrossGoals(goalIds, goalAllocations, goalTaskCounts, selectStrategyForTask) {
+    if (goalIds.length === 0)
+        return null;
+    const scored = goalIds.map((goalId) => {
+        const allocation = goalAllocations.get(goalId) ?? (1 / goalIds.length);
+        const taskCount = goalTaskCounts.get(goalId) ?? 0;
+        const saturation = allocation > 0 ? taskCount / allocation : Infinity;
+        return { goalId, saturation, allocation };
+    });
+    scored.sort((a, b) => a.saturation - b.saturation);
+    for (const { goalId, saturation } of scored) {
+        const allocation = goalAllocations.get(goalId) ?? 0;
+        if (allocation <= 0)
+            continue;
+        const selectionResult = await selectStrategyForTask(goalId);
+        if (selectionResult !== null) {
+            return {
+                goal_id: goalId,
+                strategy_id: selectionResult.strategy_id,
+                selection_reason: `Goal selected (saturation=${saturation.toFixed(2)}, allocation=${allocation.toFixed(2)}): ${selectionResult.reason}`,
+            };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=portfolio-rebalance.js.map

package/dist/portfolio-rebalance.js.map

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

package/dist/prompt/context-assembler.d.ts

@@ -0,0 +1,70 @@
+/**
+ * context-assembler.ts
+ * Assembles context from hierarchical memory layers into XML-tagged blocks for LLM prompts.
+ */
+import { type ContextPurpose } from "./slot-definitions.js";
+import { type BudgetAllocation } from "../execution/context-budget.js";
+export interface AssembledContext {
+    systemPrompt: string;
+    contextBlock: string;
+    totalTokensUsed: number;
+}
+export interface ContextAssemblerDeps {
+    stateManager?: {
+        loadGoalState(goalId: string): Promise<any | null>;
+    };
+    memoryLifecycle?: {
+        selectForWorkingMemory(goalId: string, dims: string[], tags: string[], max?: number): Promise<{
+            shortTerm: any[];
+            lessons: any[];
+        }>;
+        selectForWorkingMemorySemantic?(goalId: string, query: string, dims: string[], tags: string[], max?: number): Promise<{
+            shortTerm: any[];
+            lessons: any[];
+        }>;
+    };
+    knowledgeManager?: {
+        getRelevantKnowledge?(goalId: string): Promise<any[]>;
+        loadKnowledge?(goalId: string, tags?: string[]): Promise<any[]>;
+    };
+    contextProvider?: {
+        buildWorkspaceContextItems?(goalId: string, dimensionName: string): Promise<Array<{
+            label: string;
+            content: string;
+        }>>;
+    };
+    reflectionGetter?: (goalId: string, limit?: number) => Promise<any[]>;
+    strategyTemplateSearch?: (query: string, topK?: number) => Promise<any[]>;
+    vectorIndex?: {
+        search(query: string, topK?: number, threshold?: number): Promise<Array<{
+            id: string;
+            text: string;
+            similarity: number;
+            metadata?: Record<string, unknown>;
+        }>>;
+    };
+    budgetTokens?: number;
+    budgetAllocator?: (totalBudget: number) => BudgetAllocation;
+}
+export declare class ContextAssembler {
+    private readonly deps;
+    private readonly budget;
+    constructor(deps?: ContextAssemblerDeps);
+    build(purpose: ContextPurpose, goalId: string | undefined, dimensionName?: string, additionalContext?: Record<string, string>): Promise<AssembledContext>;
+    private applyBudgetOverrides;
+    private assembleSlot;
+    private buildGoalDefinition;
+    private buildCurrentState;
+    private buildDimensionHistory;
+    private buildRecentTaskResults;
+    private buildReflections;
+    private buildLessons;
+    private buildKnowledge;
+    private buildStrategyTemplates;
+    private buildWorkspaceState;
+    private buildFailureContext;
+    private loadGoalState;
+    private extractDimensionNames;
+    private enforceBudget;
+}
+//# sourceMappingURL=context-assembler.d.ts.map

package/dist/prompt/context-assembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-assembler.d.ts","sourceRoot":"","sources":["../../src/prompt/context-assembler.ts"],"names":[],"mappings":"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"}