instar 0.6.11 → 0.6.13

package/dist/core/EvolutionManager.js

@@ -0,0 +1,432 @@
+/**
+ * Evolution Manager — the feedback loop that turns running into evolving.
+ *
+ * Four subsystems, one principle: every interaction is an opportunity
+ * to improve. Not during batch reflection hours later, but at the
+ * moment the insight is freshest.
+ *
+ * Subsystems:
+ * 1. Evolution Queue — staged self-improvement proposals
+ * 2. Learning Registry — structured, searchable insights
+ * 3. Capability Gap Tracker — "what am I missing?"
+ * 4. Action Queue — commitment tracking with stale detection
+ *
+ * Born from Portal's engagement pipeline (Steps 8-11) and proven
+ * across 100+ evolution proposals and 10 platform engagement skills.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export class EvolutionManager {
+    stateDir;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.stateDir = config.stateDir;
+    }
+    // ── File I/O ────────────────────────────────────────────────────
+    filePath(name) {
+        return path.join(this.stateDir, 'state', 'evolution', `${name}.json`);
+    }
+    readFile(name, defaultValue) {
+        const fp = this.filePath(name);
+        if (!fs.existsSync(fp))
+            return defaultValue;
+        try {
+            return JSON.parse(fs.readFileSync(fp, 'utf-8'));
+        }
+        catch {
+            console.warn(`[EvolutionManager] Corrupted file: ${fp}`);
+            return defaultValue;
+        }
+    }
+    writeFile(name, data) {
+        const fp = this.filePath(name);
+        const dir = path.dirname(fp);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmpPath = fp + `.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+        try {
+            fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+            fs.renameSync(tmpPath, fp);
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { /* ignore */ }
+            throw err;
+        }
+    }
+    now() {
+        return new Date().toISOString();
+    }
+    // ── Evolution Queue ─────────────────────────────────────────────
+    loadEvolution() {
+        return this.readFile('evolution-queue', {
+            proposals: [],
+            stats: { totalProposals: 0, byStatus: {}, byType: {}, lastUpdated: this.now() },
+        });
+    }
+    saveEvolution(state) {
+        // Recompute stats
+        const statusCounts = {};
+        const typeCounts = {};
+        for (const p of state.proposals) {
+            statusCounts[p.status] = (statusCounts[p.status] || 0) + 1;
+            typeCounts[p.type] = (typeCounts[p.type] || 0) + 1;
+        }
+        state.stats = {
+            totalProposals: state.proposals.length,
+            byStatus: statusCounts,
+            byType: typeCounts,
+            lastUpdated: this.now(),
+        };
+        // Archive old implemented/rejected proposals if over limit
+        const max = this.config.maxProposals || 200;
+        if (state.proposals.length > max) {
+            const active = state.proposals.filter(p => !['implemented', 'rejected'].includes(p.status));
+            const archived = state.proposals.filter(p => ['implemented', 'rejected'].includes(p.status));
+            // Keep most recent archived
+            const keep = archived.slice(-Math.max(0, max - active.length));
+            state.proposals = [...active, ...keep];
+        }
+        this.writeFile('evolution-queue', state);
+    }
+    nextProposalId(state) {
+        const existing = new Set(state.proposals.map(p => p.id));
+        let num = 1;
+        while (existing.has(`EVO-${String(num).padStart(3, '0')}`))
+            num++;
+        return `EVO-${String(num).padStart(3, '0')}`;
+    }
+    addProposal(opts) {
+        const state = this.loadEvolution();
+        const id = this.nextProposalId(state);
+        const proposal = {
+            id,
+            title: opts.title,
+            source: opts.source,
+            description: opts.description,
+            type: opts.type,
+            impact: opts.impact || 'medium',
+            effort: opts.effort || 'medium',
+            status: 'proposed',
+            proposedBy: opts.proposedBy || 'agent',
+            proposedAt: this.now(),
+            tags: opts.tags,
+        };
+        state.proposals.push(proposal);
+        this.saveEvolution(state);
+        return proposal;
+    }
+    updateProposalStatus(id, status, resolution) {
+        const state = this.loadEvolution();
+        const proposal = state.proposals.find(p => p.id === id);
+        if (!proposal)
+            return false;
+        proposal.status = status;
+        if (resolution)
+            proposal.resolution = resolution;
+        if (status === 'implemented')
+            proposal.implementedAt = this.now();
+        this.saveEvolution(state);
+        return true;
+    }
+    listProposals(filter) {
+        const state = this.loadEvolution();
+        let proposals = state.proposals;
+        if (filter?.status)
+            proposals = proposals.filter(p => p.status === filter.status);
+        if (filter?.type)
+            proposals = proposals.filter(p => p.type === filter.type);
+        return proposals;
+    }
+    getEvolutionStats() {
+        return this.loadEvolution().stats;
+    }
+    // ── Learning Registry ───────────────────────────────────────────
+    loadLearnings() {
+        return this.readFile('learning-registry', {
+            learnings: [],
+            stats: { totalLearnings: 0, applied: 0, pending: 0, byCategory: {}, lastUpdated: this.now() },
+        });
+    }
+    saveLearnings(state) {
+        const categoryCounts = {};
+        let applied = 0;
+        for (const l of state.learnings) {
+            categoryCounts[l.category] = (categoryCounts[l.category] || 0) + 1;
+            if (l.applied)
+                applied++;
+        }
+        state.stats = {
+            totalLearnings: state.learnings.length,
+            applied,
+            pending: state.learnings.length - applied,
+            byCategory: categoryCounts,
+            lastUpdated: this.now(),
+        };
+        const max = this.config.maxLearnings || 500;
+        if (state.learnings.length > max) {
+            const unapplied = state.learnings.filter(l => !l.applied);
+            const appliedEntries = state.learnings.filter(l => l.applied);
+            const keep = appliedEntries.slice(-Math.max(0, max - unapplied.length));
+            state.learnings = [...unapplied, ...keep];
+        }
+        this.writeFile('learning-registry', state);
+    }
+    nextLearningId(state) {
+        const existing = new Set(state.learnings.map(l => l.id));
+        let num = 1;
+        while (existing.has(`LRN-${String(num).padStart(3, '0')}`))
+            num++;
+        return `LRN-${String(num).padStart(3, '0')}`;
+    }
+    addLearning(opts) {
+        const state = this.loadLearnings();
+        const id = this.nextLearningId(state);
+        const learning = {
+            id,
+            title: opts.title,
+            category: opts.category,
+            description: opts.description,
+            source: opts.source,
+            tags: opts.tags || [],
+            applied: false,
+            evolutionRelevance: opts.evolutionRelevance,
+        };
+        state.learnings.push(learning);
+        this.saveLearnings(state);
+        return learning;
+    }
+    markLearningApplied(id, appliedTo) {
+        const state = this.loadLearnings();
+        const learning = state.learnings.find(l => l.id === id);
+        if (!learning)
+            return false;
+        learning.applied = true;
+        learning.appliedTo = appliedTo;
+        this.saveLearnings(state);
+        return true;
+    }
+    listLearnings(filter) {
+        const state = this.loadLearnings();
+        let learnings = state.learnings;
+        if (filter?.category)
+            learnings = learnings.filter(l => l.category === filter.category);
+        if (filter?.applied !== undefined)
+            learnings = learnings.filter(l => l.applied === filter.applied);
+        return learnings;
+    }
+    getLearningStats() {
+        return this.loadLearnings().stats;
+    }
+    // ── Capability Gap Tracker ──────────────────────────────────────
+    loadGaps() {
+        return this.readFile('capability-gaps', {
+            gaps: [],
+            stats: { totalGaps: 0, bySeverity: {}, byCategory: {}, addressed: 0, lastUpdated: this.now() },
+        });
+    }
+    saveGaps(state) {
+        const severityCounts = {};
+        const categoryCounts = {};
+        let addressed = 0;
+        for (const g of state.gaps) {
+            severityCounts[g.severity] = (severityCounts[g.severity] || 0) + 1;
+            categoryCounts[g.category] = (categoryCounts[g.category] || 0) + 1;
+            if (g.status === 'addressed')
+                addressed++;
+        }
+        state.stats = {
+            totalGaps: state.gaps.length,
+            bySeverity: severityCounts,
+            byCategory: categoryCounts,
+            addressed,
+            lastUpdated: this.now(),
+        };
+        const max = this.config.maxGaps || 200;
+        if (state.gaps.length > max) {
+            const open = state.gaps.filter(g => g.status === 'identified');
+            const closed = state.gaps.filter(g => g.status !== 'identified');
+            const keep = closed.slice(-Math.max(0, max - open.length));
+            state.gaps = [...open, ...keep];
+        }
+        this.writeFile('capability-gaps', state);
+    }
+    nextGapId(state) {
+        const existing = new Set(state.gaps.map(g => g.id));
+        let num = 1;
+        while (existing.has(`GAP-${String(num).padStart(3, '0')}`))
+            num++;
+        return `GAP-${String(num).padStart(3, '0')}`;
+    }
+    addGap(opts) {
+        const state = this.loadGaps();
+        const id = this.nextGapId(state);
+        const gap = {
+            id,
+            title: opts.title,
+            category: opts.category,
+            severity: opts.severity,
+            description: opts.description,
+            discoveredFrom: {
+                context: opts.context,
+                platform: opts.platform,
+                discoveredAt: this.now(),
+                session: opts.session,
+            },
+            currentState: opts.currentState || 'Not implemented',
+            proposedSolution: opts.proposedSolution,
+            status: 'identified',
+        };
+        state.gaps.push(gap);
+        this.saveGaps(state);
+        return gap;
+    }
+    addressGap(id, resolution) {
+        const state = this.loadGaps();
+        const gap = state.gaps.find(g => g.id === id);
+        if (!gap)
+            return false;
+        gap.status = 'addressed';
+        gap.resolution = resolution;
+        gap.addressedAt = this.now();
+        this.saveGaps(state);
+        return true;
+    }
+    listGaps(filter) {
+        const state = this.loadGaps();
+        let gaps = state.gaps;
+        if (filter?.severity)
+            gaps = gaps.filter(g => g.severity === filter.severity);
+        if (filter?.category)
+            gaps = gaps.filter(g => g.category === filter.category);
+        if (filter?.status)
+            gaps = gaps.filter(g => g.status === filter.status);
+        return gaps;
+    }
+    getGapStats() {
+        return this.loadGaps().stats;
+    }
+    // ── Action Queue ────────────────────────────────────────────────
+    loadActions() {
+        return this.readFile('action-queue', {
+            actions: [],
+            stats: { totalActions: 0, pending: 0, completed: 0, overdue: 0, lastUpdated: this.now() },
+        });
+    }
+    saveActions(state) {
+        let pending = 0, completed = 0, overdue = 0;
+        const now = new Date();
+        for (const a of state.actions) {
+            if (a.status === 'completed')
+                completed++;
+            else if (a.status === 'pending' || a.status === 'in_progress') {
+                pending++;
+                if (a.dueBy && new Date(a.dueBy) < now)
+                    overdue++;
+            }
+        }
+        state.stats = {
+            totalActions: state.actions.length,
+            pending,
+            completed,
+            overdue,
+            lastUpdated: this.now(),
+        };
+        const max = this.config.maxActions || 300;
+        if (state.actions.length > max) {
+            const active = state.actions.filter(a => !['completed', 'cancelled'].includes(a.status));
+            const done = state.actions.filter(a => ['completed', 'cancelled'].includes(a.status));
+            const keep = done.slice(-Math.max(0, max - active.length));
+            state.actions = [...active, ...keep];
+        }
+        this.writeFile('action-queue', state);
+    }
+    nextActionId(state) {
+        const existing = new Set(state.actions.map(a => a.id));
+        let num = 1;
+        while (existing.has(`ACT-${String(num).padStart(3, '0')}`))
+            num++;
+        return `ACT-${String(num).padStart(3, '0')}`;
+    }
+    addAction(opts) {
+        const state = this.loadActions();
+        const id = this.nextActionId(state);
+        const action = {
+            id,
+            title: opts.title,
+            description: opts.description,
+            priority: opts.priority || 'medium',
+            status: 'pending',
+            commitTo: opts.commitTo,
+            createdAt: this.now(),
+            dueBy: opts.dueBy,
+            source: opts.source,
+            tags: opts.tags,
+        };
+        state.actions.push(action);
+        this.saveActions(state);
+        return action;
+    }
+    updateAction(id, updates) {
+        const state = this.loadActions();
+        const action = state.actions.find(a => a.id === id);
+        if (!action)
+            return false;
+        if (updates.status) {
+            action.status = updates.status;
+            if (updates.status === 'completed')
+                action.completedAt = this.now();
+        }
+        if (updates.resolution)
+            action.resolution = updates.resolution;
+        this.saveActions(state);
+        return true;
+    }
+    listActions(filter) {
+        const state = this.loadActions();
+        let actions = state.actions;
+        if (filter?.status)
+            actions = actions.filter(a => a.status === filter.status);
+        if (filter?.priority)
+            actions = actions.filter(a => a.priority === filter.priority);
+        return actions;
+    }
+    getOverdueActions() {
+        const state = this.loadActions();
+        const now = new Date();
+        return state.actions.filter(a => (a.status === 'pending' || a.status === 'in_progress') &&
+            a.dueBy && new Date(a.dueBy) < now);
+    }
+    getActionStats() {
+        return this.loadActions().stats;
+    }
+    // ── Cross-System Queries ────────────────────────────────────────
+    /**
+     * Get a full dashboard of evolution health.
+     * Useful for session-start orientation and status reporting.
+     */
+    getDashboard() {
+        const evolution = this.getEvolutionStats();
+        const learnings = this.getLearningStats();
+        const gaps = this.getGapStats();
+        const actions = this.getActionStats();
+        const overdue = this.getOverdueActions();
+        const highlights = [];
+        const proposed = evolution.byStatus['proposed'] || 0;
+        if (proposed > 0)
+            highlights.push(`${proposed} evolution proposal(s) awaiting review`);
+        if (learnings.pending > 0)
+            highlights.push(`${learnings.pending} learning(s) not yet applied`);
+        const criticalGaps = gaps.bySeverity['critical'] || 0;
+        if (criticalGaps > 0)
+            highlights.push(`${criticalGaps} critical capability gap(s)`);
+        if (overdue.length > 0)
+            highlights.push(`${overdue.length} overdue action item(s)`);
+        if (highlights.length === 0)
+            highlights.push('All systems healthy — no pending evolution items');
+        return { evolution, learnings, gaps, actions, highlights };
+    }
+}
+//# sourceMappingURL=EvolutionManager.js.map

package/dist/core/RelationshipManager.d.ts

@@ -16,8 +16,16 @@ export declare class RelationshipManager {
     private relationships;
     /** Maps "channel_type:identifier" -> relationship ID for cross-platform resolution */
     private channelIndex;
+    /** Maps normalized name -> set of relationship IDs for fuzzy name resolution */
+    private nameIndex;
     private config;
     constructor(config: RelationshipManagerConfig);
+    /** Normalize a name for fuzzy matching: lowercase, trim, collapse whitespace, strip leading @ */
+    private normalizeName;
+    /** Add a record to the name index */
+    private indexName;
+    /** Remove a record from the name index */
+    private unindexName;
     /** Validate a record ID is a valid UUID format to prevent path traversal. */
     private validateId;
     /**
@@ -26,10 +34,47 @@ export declare class RelationshipManager {
      * this returns the same relationship.
      */
     findOrCreate(name: string, channel: UserChannel): RelationshipRecord;
+    /**
+     * LLM-supervised version of findOrCreate.
+     * When an intelligence provider is configured:
+     * - Heuristics narrow candidates (channel match, name match)
+     * - LLM confirms ambiguous name matches before linking
+     * - LLM can detect matches that string heuristics miss
+     *
+     * Falls back to sync findOrCreate when no provider is available.
+     */
+    findOrCreateAsync(name: string, channel: UserChannel): Promise<RelationshipRecord>;
+    /**
+     * LLM-supervised duplicate detection.
+     * Runs heuristic findDuplicates() first, then asks the LLM to confirm
+     * each candidate group. Returns only LLM-confirmed duplicates.
+     *
+     * Falls back to heuristic-only when no provider is available.
+     */
+    findDuplicatesAsync(): Promise<Array<{
+        records: RelationshipRecord[];
+        reason: string;
+        confirmed: boolean;
+    }>>;
+    /**
+     * Ask the LLM whether a new name+channel belongs to one of the candidate records.
+     * Returns the matching record, or null if the LLM says it's a new person.
+     */
+    private askIdentityMatch;
+    /**
+     * Ask the LLM to confirm whether a group of records are truly duplicates.
+     */
+    private askDuplicateConfirmation;
     /**
      * Resolve a channel identifier to an existing relationship, or null.
      */
     resolveByChannel(channel: UserChannel): RelationshipRecord | null;
+    /**
+     * Resolve by name using fuzzy matching. Returns all matches.
+     * Handles: case differences, leading @, underscores vs hyphens vs spaces.
+     * Port of Portal's _find_existing_person() pattern.
+     */
+    resolveByName(name: string): RelationshipRecord[];
     /**
      * Get a relationship by ID.
      */
@@ -38,6 +83,16 @@ export declare class RelationshipManager {
      * Get all relationships, optionally sorted by significance or recency.
      */
     getAll(sortBy?: 'significance' | 'recent' | 'name'): RelationshipRecord[];
+    /**
+     * Detect potential duplicate relationships that could be merged.
+     * Port of Portal's find_potential_duplicates() pattern.
+     * Returns groups of records that likely represent the same person,
+     * with a reason string explaining why they were flagged.
+     */
+    findDuplicates(): Array<{
+        records: RelationshipRecord[];
+        reason: string;
+    }>;
     /**
      * Record an interaction with a person. Updates recency, count, and interaction log.
      */
@@ -62,6 +117,18 @@ export declare class RelationshipManager {
      * Delete a relationship and its disk file.
      */
     delete(id: string): boolean;
+    /**
+     * Update the category for a relationship.
+     */
+    updateCategory(id: string, category: string): void;
+    /**
+     * Add tags to a relationship (deduplicates).
+     */
+    addTags(id: string, tags: string[]): void;
+    /**
+     * Remove tags from a relationship.
+     */
+    removeTags(id: string, tags: string[]): void;
     /**
      * Generate context string for injection into a Claude session before interacting
      * with a known person. This is what makes the agent "know" who it's talking to.