instar 0.6.11 → 0.6.13

package/dist/core/RelationshipManager.js

@@ -22,6 +22,8 @@ export class RelationshipManager {
     relationships = new Map();
     /** Maps "channel_type:identifier" -> relationship ID for cross-platform resolution */
     channelIndex = new Map();
+    /** Maps normalized name -> set of relationship IDs for fuzzy name resolution */
+    nameIndex = new Map();
     config;
     constructor(config) {
         this.config = config;
@@ -30,6 +32,32 @@ export class RelationshipManager {
         }
         this.loadAll();
     }
+    /** Normalize a name for fuzzy matching: lowercase, trim, collapse whitespace, strip leading @ */
+    normalizeName(name) {
+        return name.trim().toLowerCase().replace(/^@/, '').replace(/[\s_-]+/g, ' ');
+    }
+    /** Add a record to the name index */
+    indexName(id, name) {
+        const key = this.normalizeName(name);
+        if (!key)
+            return;
+        let ids = this.nameIndex.get(key);
+        if (!ids) {
+            ids = new Set();
+            this.nameIndex.set(key, ids);
+        }
+        ids.add(id);
+    }
+    /** Remove a record from the name index */
+    unindexName(id, name) {
+        const key = this.normalizeName(name);
+        const ids = this.nameIndex.get(key);
+        if (ids) {
+            ids.delete(id);
+            if (ids.size === 0)
+                this.nameIndex.delete(key);
+        }
+    }
     /** Validate a record ID is a valid UUID format to prevent path traversal. */
     validateId(id) {
         if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) {
@@ -44,16 +72,80 @@ export class RelationshipManager {
      */
     findOrCreate(name, channel) {
         const channelKey = `${channel.type}:${channel.identifier}`;
-        // Try to resolve by channel first
+        // Try to resolve by channel first (strongest signal)
+        const existingId = this.channelIndex.get(channelKey);
+        if (existingId) {
+            const existing = this.relationships.get(existingId);
+            if (existing)
+                return existing;
+            // Channel index is stale — clean it up and fall through
+            this.channelIndex.delete(channelKey);
+        }
+        // Try name resolution before creating (prevents ColonistOne-style duplicates)
+        const nameMatches = this.resolveByName(name);
+        if (nameMatches.length === 1) {
+            // Unambiguous name match — link the new channel and return
+            const match = nameMatches[0];
+            this.linkChannel(match.id, channel);
+            return match;
+        }
+        // Create new relationship (no match, or ambiguous name)
+        const now = new Date().toISOString();
+        const record = {
+            id: randomUUID(),
+            name,
+            channels: [channel],
+            firstInteraction: now,
+            lastInteraction: now,
+            interactionCount: 0,
+            themes: [],
+            notes: '',
+            significance: 1,
+            recentInteractions: [],
+        };
+        this.relationships.set(record.id, record);
+        this.channelIndex.set(channelKey, record.id);
+        this.indexName(record.id, name);
+        this.save(record);
+        return record;
+    }
+    /**
+     * 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.
+     */
+    async findOrCreateAsync(name, channel) {
+        const intelligence = this.config.intelligence;
+        // Channel match is always definitive — no LLM needed
+        const channelKey = `${channel.type}:${channel.identifier}`;
         const existingId = this.channelIndex.get(channelKey);
         if (existingId) {
             const existing = this.relationships.get(existingId);
             if (existing)
                 return existing;
-            // Channel index is stale — clean it up and fall through to create
             this.channelIndex.delete(channelKey);
         }
-        // Create new relationship
+        // Name-based candidates (heuristic pre-filter)
+        const nameMatches = this.resolveByName(name);
+        if (nameMatches.length === 1 && !intelligence) {
+            // No LLM, unambiguous match — link directly (sync behavior)
+            const match = nameMatches[0];
+            this.linkChannel(match.id, channel);
+            return match;
+        }
+        if (nameMatches.length >= 1 && intelligence) {
+            // LLM confirms: is this new interaction from one of the existing people?
+            const confirmed = await this.askIdentityMatch(intelligence, name, channel, nameMatches);
+            if (confirmed) {
+                this.linkChannel(confirmed.id, channel);
+                return confirmed;
+            }
+        }
+        // Create new (no match, or LLM said no match)
         const now = new Date().toISOString();
         const record = {
             id: randomUUID(),
@@ -69,9 +161,110 @@ export class RelationshipManager {
         };
         this.relationships.set(record.id, record);
         this.channelIndex.set(channelKey, record.id);
+        this.indexName(record.id, name);
         this.save(record);
         return record;
     }
+    /**
+     * 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.
+     */
+    async findDuplicatesAsync() {
+        const candidates = this.findDuplicates();
+        const intelligence = this.config.intelligence;
+        if (!intelligence) {
+            return candidates.map((g) => ({ ...g, confirmed: false }));
+        }
+        const results = [];
+        for (const group of candidates) {
+            const confirmed = await this.askDuplicateConfirmation(intelligence, group.records, group.reason);
+            results.push({ ...group, confirmed });
+        }
+        return results;
+    }
+    // ── LLM Intelligence Prompts ────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async askIdentityMatch(intelligence, name, channel, candidates) {
+        const candidateDescriptions = candidates.map((r, i) => {
+            const channels = r.channels.map((c) => `${c.type}:${c.identifier}`).join(', ');
+            const themes = r.themes.slice(0, 5).join(', ') || 'none';
+            return `[${i}] "${r.name}" — channels: ${channels} — themes: ${themes} — interactions: ${r.interactionCount}`;
+        }).join('\n');
+        const prompt = `You are an identity resolution system. Determine if a new interaction belongs to an existing person.
+
+New interaction:
+- Name: "${name}"
+- Channel: ${channel.type}:${channel.identifier}
+
+Existing candidates:
+${candidateDescriptions}
+
+Does the new interaction belong to one of these existing people? Consider:
+- Name similarity (case, spacing, special characters, abbreviations)
+- Platform conventions (same person may use different handles across platforms)
+- When uncertain, prefer creating a new record over a false merge
+
+Respond with ONLY one of:
+- MATCH:N (where N is the candidate index, e.g., MATCH:0)
+- NEW (if this is a different person)`;
+        try {
+            const response = await intelligence.evaluate(prompt, { model: 'fast', maxTokens: 20, temperature: 0 });
+            const trimmed = response.trim().toUpperCase();
+            const matchResult = trimmed.match(/^MATCH:(\d+)/);
+            if (matchResult) {
+                const index = parseInt(matchResult[1], 10);
+                if (index >= 0 && index < candidates.length) {
+                    return candidates[index];
+                }
+            }
+            // LLM explicitly said NEW — respect the decision
+            if (trimmed.startsWith('NEW')) {
+                return null;
+            }
+        }
+        catch {
+            // LLM call failed — fall back to heuristic behavior
+        }
+        // Default to heuristic: single unambiguous match → link, else new
+        return candidates.length === 1 ? candidates[0] : null;
+    }
+    /**
+     * Ask the LLM to confirm whether a group of records are truly duplicates.
+     */
+    async askDuplicateConfirmation(intelligence, records, reason) {
+        const descriptions = records.map((r, i) => {
+            const channels = r.channels.map((c) => `${c.type}:${c.identifier}`).join(', ');
+            const themes = r.themes.slice(0, 5).join(', ') || 'none';
+            return `[${i}] "${r.name}" — channels: ${channels} — themes: ${themes} — notes: ${(r.notes || '').slice(0, 100)}`;
+        }).join('\n');
+        const prompt = `You are an identity resolution system. Determine if these relationship records represent the same person.
+
+Flagged reason: ${reason}
+
+Records:
+${descriptions}
+
+Are these the same person? Consider:
+- Same name with different formatting is likely the same person
+- Different names on different platforms could be the same person if context aligns
+- Different themes/topics alone don't mean different people
+- When uncertain, say NO to avoid false merges
+
+Respond with ONLY: YES or NO`;
+        try {
+            const response = await intelligence.evaluate(prompt, { model: 'fast', maxTokens: 10, temperature: 0 });
+            return response.trim().toUpperCase().startsWith('YES');
+        }
+        catch {
+            return false; // Fail safe: don't confirm on error
+        }
+    }
     /**
      * Resolve a channel identifier to an existing relationship, or null.
      */
@@ -80,6 +273,45 @@ export class RelationshipManager {
         const id = this.channelIndex.get(channelKey);
         return id ? this.relationships.get(id) ?? null : 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) {
+        const key = this.normalizeName(name);
+        if (!key)
+            return [];
+        const results = [];
+        const seen = new Set();
+        // Exact normalized match
+        const exactIds = this.nameIndex.get(key);
+        if (exactIds) {
+            for (const id of exactIds) {
+                const r = this.relationships.get(id);
+                if (r && !seen.has(id)) {
+                    results.push(r);
+                    seen.add(id);
+                }
+            }
+        }
+        // Collapsed match (remove all separators): catches "ColonistOne" vs "colonist one"
+        const collapsed = key.replace(/\s/g, '');
+        for (const [indexKey, ids] of this.nameIndex) {
+            if (indexKey.replace(/\s/g, '') === collapsed) {
+                for (const id of ids) {
+                    if (!seen.has(id)) {
+                        const r = this.relationships.get(id);
+                        if (r) {
+                            results.push(r);
+                            seen.add(id);
+                        }
+                    }
+                }
+            }
+        }
+        return results;
+    }
     /**
      * Get a relationship by ID.
      */
@@ -100,6 +332,64 @@ export class RelationshipManager {
                 return all.sort((a, b) => a.name.localeCompare(b.name));
         }
     }
+    /**
+     * 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() {
+        const groups = [];
+        const seen = new Set();
+        // Check for name collisions (same normalized name, different records)
+        for (const [key, ids] of this.nameIndex) {
+            if (ids.size > 1) {
+                const records = Array.from(ids)
+                    .map((id) => this.relationships.get(id))
+                    .filter((r) => r != null);
+                if (records.length > 1) {
+                    const groupKey = Array.from(ids).sort().join(',');
+                    if (!seen.has(groupKey)) {
+                        seen.add(groupKey);
+                        groups.push({
+                            records,
+                            reason: `Same normalized name: "${key}"`,
+                        });
+                    }
+                }
+            }
+        }
+        // Check for collapsed-name collisions (e.g., "colonist one" vs "colonistone")
+        const collapsedMap = new Map();
+        for (const [key, ids] of this.nameIndex) {
+            const collapsed = key.replace(/\s/g, '');
+            let existing = collapsedMap.get(collapsed);
+            if (!existing) {
+                existing = new Set();
+                collapsedMap.set(collapsed, existing);
+            }
+            for (const id of ids)
+                existing.add(id);
+        }
+        for (const [collapsed, ids] of collapsedMap) {
+            if (ids.size > 1) {
+                const groupKey = Array.from(ids).sort().join(',');
+                if (!seen.has(groupKey)) {
+                    seen.add(groupKey);
+                    const records = Array.from(ids)
+                        .map((id) => this.relationships.get(id))
+                        .filter((r) => r != null);
+                    if (records.length > 1) {
+                        groups.push({
+                            records,
+                            reason: `Similar collapsed name: "${collapsed}"`,
+                        });
+                    }
+                }
+            }
+        }
+        return groups;
+    }
     // ── Enrichment ─────────────────────────────────────────────────────
     /**
      * Record an interaction with a person. Updates recency, count, and interaction log.
@@ -216,9 +506,23 @@ export class RelationshipManager {
                 ? `${keep.notes}\n\n[Merged from ${merge.name}]: ${merge.notes}`.slice(0, MAX_NOTES_LENGTH)
                 : merge.notes.slice(0, MAX_NOTES_LENGTH);
         }
+        // Merge category (keep existing, or take from merged)
+        if (!keep.category && merge.category) {
+            keep.category = merge.category;
+        }
+        // Merge tags
+        if (merge.tags) {
+            if (!keep.tags)
+                keep.tags = [];
+            for (const tag of merge.tags) {
+                if (!keep.tags.includes(tag))
+                    keep.tags.push(tag);
+            }
+        }
         keep.significance = this.calculateSignificance(keep);
         this.save(keep);
-        // Delete the merged record
+        // Delete the merged record and clean up name index
+        this.unindexName(mergeId, merge.name);
         this.relationships.delete(mergeId);
         this.deleteFile(mergeId);
     }
@@ -236,10 +540,48 @@ export class RelationshipManager {
                 this.channelIndex.delete(channelKey);
             }
         }
+        // Remove name index entry
+        this.unindexName(id, record.name);
         this.relationships.delete(id);
         this.deleteFile(id);
         return true;
     }
+    /**
+     * Update the category for a relationship.
+     */
+    updateCategory(id, category) {
+        const record = this.relationships.get(id);
+        if (!record)
+            return;
+        record.category = category;
+        this.save(record);
+    }
+    /**
+     * Add tags to a relationship (deduplicates).
+     */
+    addTags(id, tags) {
+        const record = this.relationships.get(id);
+        if (!record)
+            return;
+        if (!record.tags)
+            record.tags = [];
+        for (const tag of tags) {
+            if (!record.tags.includes(tag)) {
+                record.tags.push(tag);
+            }
+        }
+        this.save(record);
+    }
+    /**
+     * Remove tags from a relationship.
+     */
+    removeTags(id, tags) {
+        const record = this.relationships.get(id);
+        if (!record || !record.tags)
+            return;
+        record.tags = record.tags.filter((t) => !tags.includes(t));
+        this.save(record);
+    }
     // ── Context Generation ─────────────────────────────────────────────
     /**
      * Generate context string for injection into a Claude session before interacting
@@ -260,6 +602,17 @@ export class RelationshipManager {
             `Total interactions: ${record.interactionCount}`,
             `Significance: ${record.significance}/10`,
         ];
+        // Cross-platform presence summary
+        if (record.channels.length > 1) {
+            const platforms = [...new Set(record.channels.map((c) => c.type))];
+            lines.push(`Platforms: ${platforms.map(sanitize).join(', ')}`);
+        }
+        if (record.category) {
+            lines.push(`Category: ${sanitize(record.category)}`);
+        }
+        if (record.tags && record.tags.length > 0) {
+            lines.push(`Tags: ${record.tags.map(sanitize).join(', ')}`);
+        }
         if (record.themes.length > 0) {
             lines.push(`Key themes: ${record.themes.map(sanitize).join(', ')}`);
         }
@@ -306,6 +659,7 @@ export class RelationshipManager {
                 }
                 this.validateId(data.id);
                 this.relationships.set(data.id, data);
+                this.indexName(data.id, data.name);
                 for (const channel of (data.channels ?? [])) {
                     this.channelIndex.set(`${channel.type}:${channel.identifier}`, data.id);
                 }

package/dist/core/SessionManager.d.ts

@@ -86,7 +86,9 @@ export declare class SessionManager extends EventEmitter {
      * Used for Telegram-driven conversational sessions.
      * Optionally sends an initial message after Claude is ready.
      */
-    spawnInteractiveSession(initialMessage?: string, name?: string): Promise<string>;
+    spawnInteractiveSession(initialMessage?: string, name?: string, options?: {
+        telegramTopicId?: number;
+    }): Promise<string>;
     /**
      * Inject a Telegram message into a tmux session.
      * Short messages go via send-keys; long messages are written to a temp file.

package/dist/core/SessionManager.js

@@ -334,7 +334,7 @@ export class SessionManager extends EventEmitter {
      * Used for Telegram-driven conversational sessions.
      * Optionally sends an initial message after Claude is ready.
      */
-    async spawnInteractiveSession(initialMessage, name) {
+    async spawnInteractiveSession(initialMessage, name, options) {
         const sanitized = name
             ? name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').slice(0, 40)
             : null;
@@ -360,16 +360,24 @@ export class SessionManager extends EventEmitter {
             throw new Error(`Max sessions (${interactiveLimit}, including interactive reserve) reached. ` +
                 `Running: ${runningSessions.map(s => s.name).join(', ')}`);
         }
-        // Spawn Claude directly — no bash -c shell intermediary.
-        // tmux -c sets the working directory; the command is passed as arguments.
+        // Spawn Claude in tmux. When a Telegram topic triggered the session,
+        // export the topic ID as an env var so hooks can prime Claude to respond.
         try {
-            execFileSync(this.config.tmuxPath, [
+            const tmuxArgs = [
                 'new-session', '-d',
                 '-s', tmuxSession,
                 '-c', this.config.projectDir,
                 '-x', '200', '-y', '50',
-                this.config.claudePath, '--dangerously-skip-permissions',
-            ], { encoding: 'utf-8' });
+            ];
+            if (options?.telegramTopicId) {
+                // Wrap in bash shell to export env var before Claude starts
+                const claudeCmd = `${this.config.claudePath} --dangerously-skip-permissions`;
+                tmuxArgs.push('bash', '-c', `export INSTAR_TELEGRAM_TOPIC=${options.telegramTopicId} && exec ${claudeCmd}`);
+            }
+            else {
+                tmuxArgs.push(this.config.claudePath, '--dangerously-skip-permissions');
+            }
+            execFileSync(this.config.tmuxPath, tmuxArgs, { encoding: 'utf-8' });
         }
         catch (err) {
             throw new Error(`Failed to create interactive tmux session: ${err}`);