conatus 0.1.0

package/dist/traits/trust-manager.d.ts

@@ -0,0 +1,90 @@
+import type { StateManager } from "../state-manager.js";
+import type { TrustBalance, ActionQuadrant } from "../types/trust.js";
+import type { PluginMatchResult } from "../types/plugin.js";
+import type { PluginLoader } from "../runtime/plugin-loader.js";
+/**
+ * TrustManager handles per-domain trust balances, action quadrant determination,
+ * irreversibility-based approval requirements, and user overrides.
+ *
+ * Persistence: `trust/trust-store.json` via StateManager readRaw/writeRaw.
+ * The store is loaded lazily on first access and cached in memory.
+ * Every mutation persists immediately.
+ */
+export declare class TrustManager {
+    private readonly stateManager;
+    private cache;
+    /** In-memory sliding window of success call timestamps per domain */
+    private successTimestamps;
+    constructor(stateManager: StateManager);
+    private loadStore;
+    private saveStore;
+    /**
+     * Get the trust balance for a domain.
+     * Returns a default balance (score=0) if the domain is not yet tracked.
+     */
+    getBalance(domain: string): Promise<TrustBalance>;
+    /**
+     * Record a successful task for a domain.
+     * Adds TRUST_SUCCESS_DELTA (+3), clamps to [-100, +100], and persists.
+     *
+     * Rate limit: if 3+ success calls occurred in the last 1 hour for this domain,
+     * the delta is skipped (but the current balance is still returned).
+     */
+    recordSuccess(domain: string): Promise<TrustBalance>;
+    /**
+     * Record a failed task for a domain.
+     * Adds TRUST_FAILURE_DELTA (-10), clamps to [-100, +100], and persists.
+     */
+    recordFailure(domain: string): Promise<TrustBalance>;
+    /**
+     * Determine the action quadrant based on trust balance and confidence.
+     *
+     * Matrix:
+     *   trust >= 20 AND confidence >= 0.50 → "autonomous"
+     *   trust >= 20 AND confidence < 0.50  → "execute_with_confirm"
+     *   trust <  20 AND confidence >= 0.50 → "execute_with_confirm"
+     *   trust <  20 AND confidence < 0.50  → "observe_and_propose"
+     */
+    getActionQuadrant(domain: string, confidence: number): Promise<ActionQuadrant>;
+    /**
+     * Determine whether an action requires human approval.
+     *
+     * Returns true if:
+     *   - reversibility is "irreversible" or "unknown" (always requires approval), OR
+     *   - a permanent gate exists for the given domain and category, OR
+     *   - the action quadrant is not "autonomous"
+     */
+    requiresApproval(reversibility: string, domain: string, confidence: number, category?: string): Promise<boolean>;
+    /**
+     * Override the trust balance for a domain to a specific value.
+     * Logs the override with a reason and persists.
+     */
+    setOverride(domain: string, balance: number, reason: string): Promise<void>;
+    /**
+     * Add a permanent gate for a category within a domain.
+     * Actions with this category will always require approval regardless of trust/confidence.
+     * Logs the gate addition and persists.
+     */
+    addPermanentGate(domain: string, category: string): Promise<void>;
+    /**
+     * Check whether a permanent gate exists for the given domain and category.
+     */
+    hasPermanentGate(domain: string, category: string): Promise<boolean>;
+    /**
+     * Record a successful plugin execution.
+     * Updates trust_score (+3), success_count, and usage_count in PluginState.
+     */
+    recordPluginSuccess(pluginName: string, pluginLoader: PluginLoader): void;
+    /**
+     * Record a failed plugin execution.
+     * Updates trust_score (-10), failure_count, and usage_count in PluginState.
+     */
+    recordPluginFailure(pluginName: string, pluginLoader: PluginLoader): void;
+    /**
+     * Select the best plugin from candidates.
+     * Prefers auto-selectable (trust >= 20) candidates, picking highest matchScore then trustScore.
+     * Returns null if no candidate is auto-selectable.
+     */
+    selectPlugin(candidates: PluginMatchResult[], pluginLoader: PluginLoader): PluginMatchResult | null;
+}
+//# sourceMappingURL=trust-manager.d.ts.map

package/dist/traits/trust-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-manager.d.ts","sourceRoot":"","sources":["../../src/traits/trust-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAYxD,OAAO,KAAK,EAAE,YAAY,EAAc,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAkChE;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,KAAK,CAA2B;IACxC,qEAAqE;IACrE,OAAO,CAAC,iBAAiB,CAAoC;gBAEjD,YAAY,EAAE,YAAY;YAMxB,SAAS;YAaT,SAAS;IAQvB;;;OAGG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IASvD;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAkC1D;;;OAGG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAY1D;;;;;;;;OAQG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAcpF;;;;;;;OAOG;IACG,gBAAgB,CACpB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAWnB;;;OAGG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBjF;;;;OAIG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBvE;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS1E;;;OAGG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI;IAYzE;;;OAGG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI;IAYzE;;;;OAIG;IACH,YAAY,CAAC,UAAU,EAAE,iBAAiB,EAAE,EAAE,YAAY,EAAE,YAAY,GAAG,iBAAiB,GAAG,IAAI;CAiBpG"}

package/dist/traits/trust-manager.js

@@ -0,0 +1,276 @@
+import { TrustBalanceSchema, TrustStoreSchema, TrustOverrideLogEntrySchema, } from "../types/trust.js";
+import { HIGH_TRUST_THRESHOLD, HIGH_CONFIDENCE_THRESHOLD, TRUST_SUCCESS_DELTA, TRUST_FAILURE_DELTA, } from "../types/trust.js";
+/** Path relative to StateManager base dir for the trust store */
+const TRUST_STORE_PATH = "trust/trust-store.json";
+/** Default empty TrustStore */
+function emptyStore() {
+    return TrustStoreSchema.parse({
+        balances: {},
+        permanent_gates: {},
+        override_log: [],
+    });
+}
+/** Default TrustBalance for a new domain */
+function defaultBalance(domain) {
+    return TrustBalanceSchema.parse({
+        domain,
+        balance: 0,
+        success_delta: TRUST_SUCCESS_DELTA,
+        failure_delta: TRUST_FAILURE_DELTA,
+    });
+}
+/** Clamp a value to [-100, 100] */
+function clamp(value) {
+    return Math.max(-100, Math.min(100, value));
+}
+/** Maximum success calls allowed within 1-hour sliding window before rate limiting */
+const TRUST_RATE_LIMIT_MAX = 3;
+/** Sliding window duration in milliseconds (1 hour) */
+const TRUST_RATE_LIMIT_WINDOW_MS = 3_600_000;
+/**
+ * TrustManager handles per-domain trust balances, action quadrant determination,
+ * irreversibility-based approval requirements, and user overrides.
+ *
+ * Persistence: `trust/trust-store.json` via StateManager readRaw/writeRaw.
+ * The store is loaded lazily on first access and cached in memory.
+ * Every mutation persists immediately.
+ */
+export class TrustManager {
+    stateManager;
+    cache = null;
+    /** In-memory sliding window of success call timestamps per domain */
+    successTimestamps = new Map();
+    constructor(stateManager) {
+        this.stateManager = stateManager;
+    }
+    // ─── Private: Store I/O ───
+    async loadStore() {
+        if (this.cache !== null) {
+            return this.cache;
+        }
+        const raw = await this.stateManager.readRaw(TRUST_STORE_PATH);
+        if (raw === null) {
+            this.cache = emptyStore();
+        }
+        else {
+            this.cache = TrustStoreSchema.parse(raw);
+        }
+        return this.cache;
+    }
+    async saveStore(store) {
+        const parsed = TrustStoreSchema.parse(store);
+        this.cache = parsed;
+        await this.stateManager.writeRaw(TRUST_STORE_PATH, parsed);
+    }
+    // ─── Public API ───
+    /**
+     * Get the trust balance for a domain.
+     * Returns a default balance (score=0) if the domain is not yet tracked.
+     */
+    async getBalance(domain) {
+        const store = await this.loadStore();
+        const existing = store.balances[domain];
+        if (existing === undefined) {
+            return defaultBalance(domain);
+        }
+        return TrustBalanceSchema.parse(existing);
+    }
+    /**
+     * Record a successful task for a domain.
+     * Adds TRUST_SUCCESS_DELTA (+3), clamps to [-100, +100], and persists.
+     *
+     * Rate limit: if 3+ success calls occurred in the last 1 hour for this domain,
+     * the delta is skipped (but the current balance is still returned).
+     */
+    async recordSuccess(domain) {
+        const now = Date.now();
+        const windowStart = now - TRUST_RATE_LIMIT_WINDOW_MS;
+        // Filter timestamps to the current sliding window
+        const timestamps = (this.successTimestamps.get(domain) ?? []).filter((ts) => ts >= windowStart);
+        if (timestamps.length >= TRUST_RATE_LIMIT_MAX) {
+            console.warn(`WARN: trust rate limit triggered (domain: ${domain}, window: 1h, count: ${timestamps.length})`);
+            // Store the cleaned-up timestamps and return without applying delta
+            this.successTimestamps.set(domain, timestamps);
+            const store = await this.loadStore();
+            return store.balances[domain] ?? defaultBalance(domain);
+        }
+        // Record this call and apply the delta
+        timestamps.push(now);
+        this.successTimestamps.set(domain, timestamps);
+        const store = await this.loadStore();
+        const current = store.balances[domain] ?? defaultBalance(domain);
+        const updated = TrustBalanceSchema.parse({
+            ...current,
+            balance: clamp(current.balance + TRUST_SUCCESS_DELTA),
+        });
+        store.balances[domain] = updated;
+        await this.saveStore(store);
+        return updated;
+    }
+    /**
+     * Record a failed task for a domain.
+     * Adds TRUST_FAILURE_DELTA (-10), clamps to [-100, +100], and persists.
+     */
+    async recordFailure(domain) {
+        const store = await this.loadStore();
+        const current = store.balances[domain] ?? defaultBalance(domain);
+        const updated = TrustBalanceSchema.parse({
+            ...current,
+            balance: clamp(current.balance + TRUST_FAILURE_DELTA),
+        });
+        store.balances[domain] = updated;
+        await this.saveStore(store);
+        return updated;
+    }
+    /**
+     * Determine the action quadrant based on trust balance and confidence.
+     *
+     * Matrix:
+     *   trust >= 20 AND confidence >= 0.50 → "autonomous"
+     *   trust >= 20 AND confidence < 0.50  → "execute_with_confirm"
+     *   trust <  20 AND confidence >= 0.50 → "execute_with_confirm"
+     *   trust <  20 AND confidence < 0.50  → "observe_and_propose"
+     */
+    async getActionQuadrant(domain, confidence) {
+        const { balance } = await this.getBalance(domain);
+        const highTrust = balance >= HIGH_TRUST_THRESHOLD;
+        const highConfidence = confidence >= HIGH_CONFIDENCE_THRESHOLD;
+        if (highTrust && highConfidence) {
+            return "autonomous";
+        }
+        if (!highTrust && !highConfidence) {
+            return "observe_and_propose";
+        }
+        return "execute_with_confirm";
+    }
+    /**
+     * Determine whether an action requires human approval.
+     *
+     * Returns true if:
+     *   - reversibility is "irreversible" or "unknown" (always requires approval), OR
+     *   - a permanent gate exists for the given domain and category, OR
+     *   - the action quadrant is not "autonomous"
+     */
+    async requiresApproval(reversibility, domain, confidence, category) {
+        if (reversibility === "irreversible" || reversibility === "unknown") {
+            return true;
+        }
+        if (category && await this.hasPermanentGate(domain, category)) {
+            return true;
+        }
+        const quadrant = await this.getActionQuadrant(domain, confidence);
+        return quadrant === "observe_and_propose";
+    }
+    /**
+     * Override the trust balance for a domain to a specific value.
+     * Logs the override with a reason and persists.
+     */
+    async setOverride(domain, balance, reason) {
+        const store = await this.loadStore();
+        const current = store.balances[domain] ?? defaultBalance(domain);
+        const balanceBefore = current.balance;
+        const balanceAfter = clamp(balance);
+        const updated = TrustBalanceSchema.parse({
+            ...current,
+            balance: balanceAfter,
+        });
+        store.balances[domain] = updated;
+        const logEntry = TrustOverrideLogEntrySchema.parse({
+            timestamp: new Date().toISOString(),
+            override_type: "trust_grant",
+            domain,
+            target_category: null,
+            balance_before: balanceBefore,
+            balance_after: balanceAfter,
+        });
+        store.override_log.push(logEntry);
+        await this.saveStore(store);
+    }
+    /**
+     * Add a permanent gate for a category within a domain.
+     * Actions with this category will always require approval regardless of trust/confidence.
+     * Logs the gate addition and persists.
+     */
+    async addPermanentGate(domain, category) {
+        const store = await this.loadStore();
+        if (!store.permanent_gates[domain]) {
+            store.permanent_gates[domain] = [];
+        }
+        if (!store.permanent_gates[domain].includes(category)) {
+            store.permanent_gates[domain].push(category);
+        }
+        const logEntry = TrustOverrideLogEntrySchema.parse({
+            timestamp: new Date().toISOString(),
+            override_type: "permanent_gate",
+            domain,
+            target_category: category,
+            balance_before: null,
+            balance_after: null,
+        });
+        store.override_log.push(logEntry);
+        await this.saveStore(store);
+    }
+    /**
+     * Check whether a permanent gate exists for the given domain and category.
+     */
+    async hasPermanentGate(domain, category) {
+        const store = await this.loadStore();
+        const gates = store.permanent_gates[domain];
+        if (!gates)
+            return false;
+        return gates.includes(category);
+    }
+    // ─── Plugin trust ───
+    /**
+     * Record a successful plugin execution.
+     * Updates trust_score (+3), success_count, and usage_count in PluginState.
+     */
+    recordPluginSuccess(pluginName, pluginLoader) {
+        const state = pluginLoader.getPluginState(pluginName);
+        if (state === null)
+            return;
+        pluginLoader.updatePluginState(pluginName, {
+            trust_score: clamp(state.trust_score + TRUST_SUCCESS_DELTA),
+            success_count: state.success_count + 1,
+            usage_count: state.usage_count + 1,
+        }).catch((err) => {
+            console.warn('updatePluginState failed (recordPluginSuccess)', String(err));
+        });
+    }
+    /**
+     * Record a failed plugin execution.
+     * Updates trust_score (-10), failure_count, and usage_count in PluginState.
+     */
+    recordPluginFailure(pluginName, pluginLoader) {
+        const state = pluginLoader.getPluginState(pluginName);
+        if (state === null)
+            return;
+        pluginLoader.updatePluginState(pluginName, {
+            trust_score: clamp(state.trust_score + TRUST_FAILURE_DELTA),
+            failure_count: state.failure_count + 1,
+            usage_count: state.usage_count + 1,
+        }).catch((err) => {
+            console.warn('updatePluginState failed (recordPluginFailure)', String(err));
+        });
+    }
+    /**
+     * Select the best plugin from candidates.
+     * Prefers auto-selectable (trust >= 20) candidates, picking highest matchScore then trustScore.
+     * Returns null if no candidate is auto-selectable.
+     */
+    selectPlugin(candidates, pluginLoader) {
+        // Enrich candidates with current trust scores from pluginLoader
+        const enriched = candidates.map((c) => {
+            const state = pluginLoader.getPluginState(c.pluginName);
+            const trustScore = state !== null ? state.trust_score : c.trustScore;
+            return { ...c, trustScore, autoSelectable: trustScore >= HIGH_TRUST_THRESHOLD };
+        });
+        const autoSelectable = enriched.filter((c) => c.autoSelectable);
+        if (autoSelectable.length === 0)
+            return null;
+        // Sort by matchScore desc, then trustScore desc
+        autoSelectable.sort((a, b) => b.matchScore !== a.matchScore ? b.matchScore - a.matchScore : b.trustScore - a.trustScore);
+        return autoSelectable[0];
+    }
+}
+//# sourceMappingURL=trust-manager.js.map

package/dist/traits/trust-manager.js.map

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

package/dist/tree-loop-orchestrator.d.ts

@@ -0,0 +1,79 @@
+import type { StateManager } from "./state-manager.js";
+import type { GoalTreeManager } from "./goal-tree-manager.js";
+import type { StateAggregator } from "./state-aggregator.js";
+import type { SatisficingJudge } from "./drive/satisficing-judge.js";
+import type { GoalDecompositionConfig } from "./types/goal-tree.js";
+/**
+ * TreeLoopOrchestrator manages the execution of independent loops across
+ * all nodes in a goal tree.
+ *
+ * Responsibilities:
+ *   - Selecting the next node to execute (leaf-first priority)
+ *   - Enforcing parallel_loop_limit for concurrent execution
+ *   - Tracking loop_status transitions (idle → running → idle/paused)
+ *   - Triggering state aggregation on node completion
+ *   - Detecting and cascading completion up the tree
+ *
+ * Design ref: docs/design/goal-tree.md §14C
+ */
+export declare class TreeLoopOrchestrator {
+    private readonly stateManager;
+    private readonly goalTreeManager;
+    private readonly stateAggregator;
+    private readonly satisficingJudge;
+    /**
+     * GoalDecompositionConfig used to control parallel execution limits.
+     * Updated by startTreeExecution(); defaults applied until first call.
+     */
+    private config;
+    constructor(stateManager: StateManager, goalTreeManager: GoalTreeManager, stateAggregator: StateAggregator, satisficingJudge: SatisficingJudge);
+    /**
+     * Initialize tree execution.
+     * Saves the config and optionally resets all node loop_status to "idle".
+     * The actual per-node loops are driven by CoreLoop calling selectNextNode()
+     * in a tree-mode iteration.
+     */
+    startTreeExecution(rootId: string, config: GoalDecompositionConfig): Promise<void>;
+    /**
+     * Select the next node to execute from the tree rooted at rootId.
+     *
+     * Algorithm (MVP: leaf-first):
+     *   1. Get tree state — if active_loops.length >= parallel_loop_limit, return null.
+     *   2. Collect all goal IDs in the tree (root + descendants).
+     *   3. Filter to active + idle nodes (not running, not paused).
+     *   4. Prefer leaf nodes (node_type === "leaf") over non-leaf nodes.
+     *   5. Return the first candidate's ID and set its loop_status to "running".
+     *
+     * Returns null when:
+     *   - parallel_loop_limit is already reached
+     *   - No eligible (active + idle) nodes remain
+     */
+    selectNextNode(rootId: string): string | null;
+    /**
+     * Pause the loop for a specific node.
+     * Sets loop_status to "paused".
+     * No-op if the goal is not found.
+     */
+    pauseNodeLoop(goalId: string): void;
+    /**
+     * Resume the loop for a specific node.
+     * Sets loop_status to "running".
+     * No-op if the goal is not found.
+     */
+    resumeNodeLoop(goalId: string): void;
+    /**
+     * Called when a node's execution cycle completes.
+     *
+     * Actions:
+     *   1. Reset loop_status to "idle" (release the execution slot).
+     *   2. Aggregate state bottom-up to the root.
+     *   3. Run completion cascade to auto-complete ancestor nodes whose
+     *      children are all done.
+     */
+    onNodeCompleted(goalId: string): void;
+    /**
+     * Collect all descendant IDs (not including rootId itself).
+     */
+    private _collectAllDescendantIds;
+}
+//# sourceMappingURL=tree-loop-orchestrator.d.ts.map

package/dist/tree-loop-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-loop-orchestrator.d.ts","sourceRoot":"","sources":["../src/tree-loop-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAoB;IAa7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAfnC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAKZ;gBAGiB,YAAY,EAAE,YAAY,EAC1B,eAAe,EAAE,eAAe,EAChC,eAAe,EAAE,eAAe,EAChC,gBAAgB,EAAE,gBAAgB;IAKrD;;;;;OAKG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,IAAI,CAAC;IAwBhB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA6D7C;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAWnC;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAapC;;;;;;;;OAQG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IA0CrC;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAUjC"}