attocode 0.2.3 → 0.2.5

package/dist/src/integrations/agents/shared-blackboard.js

@@ -0,0 +1,757 @@
+/**
+ * Shared Blackboard Integration
+ *
+ * Implements the Blackboard pattern for subagent coordination.
+ * Enables real-time knowledge sharing between parallel agents without
+ * tight coupling.
+ *
+ * Key features:
+ * - Finding posting: Agents share discoveries as they work
+ * - Topic subscriptions: Agents subscribe to relevant findings
+ * - Resource claiming: Prevent file edit conflicts
+ * - Deduplication: Avoid researching what another agent already found
+ * - Query interface: Search findings by topic, agent, or content
+ */
+// =============================================================================
+// SHARED BLACKBOARD
+// =============================================================================
+/**
+ * Shared blackboard for subagent coordination.
+ *
+ * @example
+ * ```typescript
+ * const blackboard = createSharedBlackboard();
+ *
+ * // Agent A posts a finding
+ * blackboard.post('agent-a', {
+ *   topic: 'authentication',
+ *   content: 'Found JWT implementation in src/auth/jwt.ts',
+ *   type: 'discovery',
+ *   confidence: 0.9,
+ *   relatedFiles: ['src/auth/jwt.ts'],
+ * });
+ *
+ * // Agent B subscribes to authentication findings
+ * blackboard.subscribe({
+ *   agentId: 'agent-b',
+ *   topicPattern: 'auth*',
+ *   callback: (finding) => {
+ *     console.log('Got finding:', finding.content);
+ *   },
+ * });
+ *
+ * // Agent A claims a file for editing
+ * const claimed = blackboard.claim('src/auth/jwt.ts', 'agent-a', 'write');
+ * if (claimed) {
+ *   // Safe to edit
+ * }
+ * ```
+ */
+export class SharedBlackboard {
+    config;
+    findings = new Map();
+    claims = new Map();
+    subscriptions = new Map();
+    listeners = [];
+    duplicatesAvoided = 0;
+    findingCounter = 0;
+    subscriptionCounter = 0;
+    /** Optional trace collector for emitting blackboard.event trace events. */
+    traceCollector;
+    constructor(config = {}) {
+        this.config = {
+            maxFindings: config.maxFindings ?? 1000,
+            defaultClaimTTL: config.defaultClaimTTL ?? 60000, // 1 minute
+            deduplicateFindings: config.deduplicateFindings ?? true,
+            deduplicationThreshold: config.deduplicationThreshold ?? 0.85,
+            persistToFile: config.persistToFile ?? false,
+            persistencePath: config.persistencePath ?? '.blackboard.json',
+        };
+        // Start claim expiry checker
+        this.startClaimExpiryChecker();
+    }
+    // ===========================================================================
+    // FINDINGS
+    // ===========================================================================
+    /**
+     * Post a finding to the blackboard.
+     */
+    post(agentId, input) {
+        // Check for duplicates
+        if (this.config.deduplicateFindings) {
+            const duplicate = this.findDuplicate(input);
+            if (duplicate) {
+                this.duplicatesAvoided++;
+                return duplicate;
+            }
+        }
+        const finding = {
+            ...input,
+            id: `finding-${++this.findingCounter}-${Date.now()}`,
+            agentId,
+            timestamp: new Date(),
+        };
+        // Handle supersession
+        if (finding.supersedesId) {
+            this.emit({
+                type: 'finding.superseded',
+                oldId: finding.supersedesId,
+                newId: finding.id,
+            });
+        }
+        // Enforce max findings
+        if (this.findings.size >= this.config.maxFindings) {
+            this.evictOldestFinding();
+        }
+        this.findings.set(finding.id, finding);
+        this.emit({ type: 'finding.posted', finding });
+        // Emit trace event for finding posted
+        this.traceCollector?.record({
+            type: 'blackboard.event',
+            data: {
+                action: 'finding.posted',
+                agentId: finding.agentId,
+                topic: finding.topic,
+                content: finding.content.slice(0, 200),
+                confidence: finding.confidence,
+                findingType: finding.type,
+                relatedFiles: finding.relatedFiles,
+            },
+        });
+        // Notify subscribers
+        this.notifySubscribers(finding);
+        return finding;
+    }
+    /**
+     * Update an existing finding.
+     */
+    update(findingId, updates) {
+        const existing = this.findings.get(findingId);
+        if (!existing)
+            return null;
+        const updated = {
+            ...existing,
+            ...updates,
+        };
+        this.findings.set(findingId, updated);
+        this.emit({ type: 'finding.updated', finding: updated });
+        // Emit trace event for finding updated
+        this.traceCollector?.record({
+            type: 'blackboard.event',
+            data: {
+                action: 'finding.updated',
+                agentId: updated.agentId,
+                topic: updated.topic,
+                content: updated.content.slice(0, 200),
+                confidence: updated.confidence,
+                findingType: updated.type,
+                relatedFiles: updated.relatedFiles,
+            },
+        });
+        return updated;
+    }
+    /**
+     * Get a finding by ID.
+     */
+    getFinding(id) {
+        return this.findings.get(id);
+    }
+    /**
+     * Query findings with filters.
+     */
+    query(filter = {}) {
+        let results = Array.from(this.findings.values());
+        // Apply filters
+        if (filter.agentId) {
+            results = results.filter((f) => f.agentId === filter.agentId);
+        }
+        if (filter.topic) {
+            const pattern = this.topicToRegex(filter.topic);
+            results = results.filter((f) => pattern.test(f.topic));
+        }
+        if (filter.types && filter.types.length > 0) {
+            results = results.filter((f) => filter.types.includes(f.type));
+        }
+        if (filter.tags && filter.tags.length > 0) {
+            results = results.filter((f) => f.tags?.some((tag) => filter.tags.includes(tag)));
+        }
+        if (filter.minConfidence !== undefined) {
+            results = results.filter((f) => f.confidence >= filter.minConfidence);
+        }
+        if (filter.since) {
+            results = results.filter((f) => f.timestamp >= filter.since);
+        }
+        if (filter.relatedFiles && filter.relatedFiles.length > 0) {
+            results = results.filter((f) => f.relatedFiles?.some((file) => filter.relatedFiles.includes(file)));
+        }
+        if (filter.contentSearch) {
+            const searchLower = filter.contentSearch.toLowerCase();
+            results = results.filter((f) => f.content.toLowerCase().includes(searchLower));
+        }
+        // Sort by timestamp (newest first)
+        results.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+        // Apply limit
+        if (filter.limit) {
+            results = results.slice(0, filter.limit);
+        }
+        return results;
+    }
+    /**
+     * Get all findings.
+     */
+    getAllFindings() {
+        return Array.from(this.findings.values());
+    }
+    /**
+     * Get findings by topic.
+     */
+    getByTopic(topic) {
+        return this.query({ topic });
+    }
+    /**
+     * Get findings by agent.
+     */
+    getByAgent(agentId) {
+        return this.query({ agentId });
+    }
+    /**
+     * Check if a finding similar to the input already exists.
+     */
+    findDuplicate(input) {
+        for (const existing of this.findings.values()) {
+            if (existing.topic === input.topic && existing.type === input.type) {
+                const similarity = this.calculateSimilarity(existing.content, input.content);
+                if (similarity >= this.config.deduplicationThreshold) {
+                    return existing;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Calculate content similarity (simple Jaccard index).
+     */
+    calculateSimilarity(a, b) {
+        const wordsA = new Set(a.toLowerCase().split(/\s+/));
+        const wordsB = new Set(b.toLowerCase().split(/\s+/));
+        const intersection = new Set([...wordsA].filter((x) => wordsB.has(x)));
+        const union = new Set([...wordsA, ...wordsB]);
+        return intersection.size / union.size;
+    }
+    /**
+     * Evict the oldest finding.
+     */
+    evictOldestFinding() {
+        let oldest = null;
+        let oldestTime = Infinity;
+        for (const finding of this.findings.values()) {
+            const time = finding.timestamp.getTime();
+            if (time < oldestTime) {
+                oldestTime = time;
+                oldest = finding;
+            }
+        }
+        if (oldest) {
+            this.findings.delete(oldest.id);
+        }
+    }
+    // ===========================================================================
+    // SUBSCRIPTIONS
+    // ===========================================================================
+    /**
+     * Subscribe to findings matching a pattern.
+     */
+    subscribe(options) {
+        const subscription = {
+            ...options,
+            id: `sub-${++this.subscriptionCounter}-${Date.now()}`,
+            createdAt: new Date(),
+        };
+        this.subscriptions.set(subscription.id, subscription);
+        return subscription.id;
+    }
+    /**
+     * Unsubscribe from findings.
+     */
+    unsubscribe(subscriptionId) {
+        return this.subscriptions.delete(subscriptionId);
+    }
+    /**
+     * Unsubscribe all subscriptions for an agent.
+     */
+    unsubscribeAgent(agentId) {
+        let count = 0;
+        for (const [id, sub] of this.subscriptions) {
+            if (sub.agentId === agentId) {
+                this.subscriptions.delete(id);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Notify matching subscribers of a new finding.
+     */
+    notifySubscribers(finding) {
+        for (const [id, sub] of this.subscriptions) {
+            if (this.matchesSubscription(finding, sub)) {
+                try {
+                    sub.callback(finding);
+                    this.emit({
+                        type: 'subscription.matched',
+                        subscriptionId: id,
+                        findingId: finding.id,
+                    });
+                }
+                catch {
+                    // Ignore callback errors
+                }
+            }
+        }
+    }
+    /**
+     * Check if a finding matches a subscription.
+     */
+    matchesSubscription(finding, sub) {
+        // Don't notify the posting agent
+        if (finding.agentId === sub.agentId) {
+            return false;
+        }
+        // Check topic pattern
+        if (sub.topicPattern) {
+            const pattern = this.topicToRegex(sub.topicPattern);
+            if (!pattern.test(finding.topic)) {
+                return false;
+            }
+        }
+        // Check types
+        if (sub.types && sub.types.length > 0) {
+            if (!sub.types.includes(finding.type)) {
+                return false;
+            }
+        }
+        // Check tags
+        if (sub.tags && sub.tags.length > 0) {
+            if (!finding.tags?.some((tag) => sub.tags.includes(tag))) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Convert a topic pattern to a regex.
+     */
+    topicToRegex(pattern) {
+        const escaped = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '.*')
+            .replace(/\?/g, '.');
+        return new RegExp(`^${escaped}$`, 'i');
+    }
+    // ===========================================================================
+    // RESOURCE CLAIMS
+    // ===========================================================================
+    /**
+     * Claim a resource for exclusive or shared access.
+     */
+    claim(resource, agentId, type, options = {}) {
+        const existing = this.claims.get(resource);
+        // Check for conflicts
+        if (existing) {
+            // Same agent can upgrade/extend claim
+            if (existing.agentId === agentId) {
+                const newClaim = {
+                    resource,
+                    agentId,
+                    type,
+                    claimedAt: existing.claimedAt,
+                    expiresAt: new Date(Date.now() + (options.ttl ?? this.config.defaultClaimTTL)),
+                    intent: options.intent,
+                };
+                this.claims.set(resource, newClaim);
+                return true;
+            }
+            // Check if claims are compatible
+            if (existing.type === 'exclusive' || type === 'exclusive' || type === 'write') {
+                this.emit({
+                    type: 'claim.conflict',
+                    resource,
+                    existingAgent: existing.agentId,
+                    requestingAgent: agentId,
+                });
+                return false;
+            }
+            // Read claims are compatible with other read claims
+            if (existing.type === 'read' && type === 'read') {
+                // Allow multiple read claims - but track the latest
+                // In a full implementation, we'd track multiple claims
+            }
+        }
+        const claim = {
+            resource,
+            agentId,
+            type,
+            claimedAt: new Date(),
+            expiresAt: new Date(Date.now() + (options.ttl ?? this.config.defaultClaimTTL)),
+            intent: options.intent,
+        };
+        this.claims.set(resource, claim);
+        this.emit({ type: 'claim.acquired', claim });
+        // Emit trace event for claim acquired
+        this.traceCollector?.record({
+            type: 'blackboard.event',
+            data: {
+                action: 'claim.acquired',
+                agentId: claim.agentId,
+                resource: claim.resource,
+                claimType: claim.type,
+            },
+        });
+        return true;
+    }
+    /**
+     * Release a resource claim.
+     */
+    release(resource, agentId) {
+        const existing = this.claims.get(resource);
+        if (!existing || existing.agentId !== agentId) {
+            return false;
+        }
+        this.claims.delete(resource);
+        this.emit({ type: 'claim.released', resource, agentId });
+        // Emit trace event for claim released
+        this.traceCollector?.record({
+            type: 'blackboard.event',
+            data: {
+                action: 'claim.released',
+                agentId,
+                resource,
+            },
+        });
+        return true;
+    }
+    /**
+     * Release all claims for an agent.
+     */
+    releaseAll(agentId) {
+        let count = 0;
+        for (const [resource, claim] of this.claims) {
+            if (claim.agentId === agentId) {
+                this.claims.delete(resource);
+                this.emit({ type: 'claim.released', resource, agentId });
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Check if a resource is claimed.
+     */
+    isClaimed(resource) {
+        const claim = this.claims.get(resource);
+        if (!claim)
+            return false;
+        // Check expiry
+        if (claim.expiresAt < new Date()) {
+            this.claims.delete(resource);
+            this.emit({ type: 'claim.expired', claim });
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Get the claim on a resource.
+     */
+    getClaim(resource) {
+        const claim = this.claims.get(resource);
+        if (!claim)
+            return undefined;
+        // Check expiry
+        if (claim.expiresAt < new Date()) {
+            this.claims.delete(resource);
+            this.emit({ type: 'claim.expired', claim });
+            return undefined;
+        }
+        return claim;
+    }
+    /**
+     * Get all claims by an agent.
+     */
+    getAgentClaims(agentId) {
+        const claims = [];
+        const now = new Date();
+        for (const claim of this.claims.values()) {
+            if (claim.agentId === agentId) {
+                if (claim.expiresAt < now) {
+                    this.claims.delete(claim.resource);
+                    this.emit({ type: 'claim.expired', claim });
+                }
+                else {
+                    claims.push(claim);
+                }
+            }
+        }
+        return claims;
+    }
+    /**
+     * Start periodic claim expiry checking.
+     */
+    startClaimExpiryChecker() {
+        setInterval(() => {
+            const now = new Date();
+            for (const [resource, claim] of this.claims) {
+                if (claim.expiresAt < now) {
+                    this.claims.delete(resource);
+                    this.emit({ type: 'claim.expired', claim });
+                }
+            }
+        }, 10000); // Check every 10 seconds
+    }
+    // ===========================================================================
+    // COORDINATION HELPERS
+    // ===========================================================================
+    /**
+     * Check if an agent has already researched a topic.
+     */
+    hasResearched(topic, options = {}) {
+        const findings = this.query({
+            topic,
+            types: ['discovery', 'analysis'],
+            minConfidence: options.minConfidence ?? 0.7,
+        });
+        return findings.length > 0;
+    }
+    /**
+     * Get the best finding for a topic.
+     */
+    getBestFinding(topic) {
+        const findings = this.query({ topic });
+        if (findings.length === 0)
+            return undefined;
+        // Return highest confidence
+        return findings.reduce((best, current) => current.confidence > best.confidence ? current : best);
+    }
+    /**
+     * Ask a question to other agents.
+     */
+    askQuestion(agentId, topic, question, tags) {
+        return this.post(agentId, {
+            topic,
+            content: question,
+            type: 'question',
+            confidence: 1,
+            tags,
+        });
+    }
+    /**
+     * Answer a question.
+     */
+    answerQuestion(agentId, questionId, answer, confidence) {
+        const question = this.getFinding(questionId);
+        if (!question) {
+            throw new Error(`Question ${questionId} not found`);
+        }
+        return this.post(agentId, {
+            topic: question.topic,
+            content: answer,
+            type: 'answer',
+            confidence,
+            tags: question.tags,
+            metadata: { answersQuestionId: questionId },
+        });
+    }
+    /**
+     * Report a blocker.
+     */
+    reportBlocker(agentId, topic, description, relatedFiles) {
+        return this.post(agentId, {
+            topic,
+            content: description,
+            type: 'blocker',
+            confidence: 1,
+            relatedFiles,
+        });
+    }
+    /**
+     * Report progress.
+     */
+    reportProgress(agentId, topic, description, metadata) {
+        return this.post(agentId, {
+            topic,
+            content: description,
+            type: 'progress',
+            confidence: 1,
+            metadata,
+        });
+    }
+    // ===========================================================================
+    // STATISTICS & UTILITIES
+    // ===========================================================================
+    /**
+     * Get blackboard statistics.
+     */
+    getStats() {
+        const findingsByType = new Map();
+        const findingsByAgent = new Map();
+        for (const finding of this.findings.values()) {
+            findingsByType.set(finding.type, (findingsByType.get(finding.type) ?? 0) + 1);
+            findingsByAgent.set(finding.agentId, (findingsByAgent.get(finding.agentId) ?? 0) + 1);
+        }
+        return {
+            totalFindings: this.findings.size,
+            findingsByType,
+            findingsByAgent,
+            activeClaims: this.claims.size,
+            activeSubscriptions: this.subscriptions.size,
+            duplicatesAvoided: this.duplicatesAvoided,
+        };
+    }
+    /**
+     * Generate a summary of the blackboard state.
+     */
+    summarize() {
+        const stats = this.getStats();
+        const lines = [
+            `Blackboard Summary`,
+            `==================`,
+            `Total findings: ${stats.totalFindings}`,
+            `Active claims: ${stats.activeClaims}`,
+            `Active subscriptions: ${stats.activeSubscriptions}`,
+            `Duplicates avoided: ${stats.duplicatesAvoided}`,
+            ``,
+            `Findings by type:`,
+        ];
+        for (const [type, count] of stats.findingsByType) {
+            lines.push(`  - ${type}: ${count}`);
+        }
+        lines.push(``, `Findings by agent:`);
+        for (const [agent, count] of stats.findingsByAgent) {
+            lines.push(`  - ${agent}: ${count}`);
+        }
+        // Recent findings
+        const recent = this.query({ limit: 5 });
+        if (recent.length > 0) {
+            lines.push(``, `Recent findings:`);
+            for (const f of recent) {
+                lines.push(`  - [${f.type}] ${f.topic}: ${f.content.slice(0, 50)}...`);
+            }
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Clear all data.
+     */
+    clear() {
+        this.findings.clear();
+        this.claims.clear();
+        this.subscriptions.clear();
+        this.duplicatesAvoided = 0;
+    }
+    /**
+     * Clear findings only (keep claims and subscriptions).
+     */
+    clearFindings() {
+        this.findings.clear();
+        this.duplicatesAvoided = 0;
+    }
+    /**
+     * Subscribe to blackboard events.
+     */
+    on(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx >= 0)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+}
+// =============================================================================
+// FACTORY FUNCTIONS
+// =============================================================================
+/**
+ * Create a shared blackboard.
+ *
+ * @example
+ * ```typescript
+ * // Create blackboard for a multi-agent task
+ * const blackboard = createSharedBlackboard({
+ *   maxFindings: 500,
+ *   deduplicateFindings: true,
+ * });
+ *
+ * // Agent A posts discovery
+ * blackboard.post('agent-a', {
+ *   topic: 'database.schema',
+ *   content: 'Found User table with columns: id, email, password_hash',
+ *   type: 'discovery',
+ *   confidence: 0.95,
+ *   relatedFiles: ['migrations/001_users.sql'],
+ * });
+ *
+ * // Agent B subscribes to database findings
+ * blackboard.subscribe({
+ *   agentId: 'agent-b',
+ *   topicPattern: 'database.*',
+ *   callback: (finding) => {
+ *     // Use the finding in context
+ *   },
+ * });
+ *
+ * // Agent A claims a file for editing
+ * if (blackboard.claim('src/models/user.ts', 'agent-a', 'write')) {
+ *   // Safe to edit
+ *   // ... make changes ...
+ *   blackboard.release('src/models/user.ts', 'agent-a');
+ * }
+ * ```
+ */
+export function createSharedBlackboard(config = {}) {
+    return new SharedBlackboard(config);
+}
+/**
+ * Create a context-aware finding from agent output.
+ */
+export function createFindingFromOutput(_agentId, output, options) {
+    return {
+        topic: options.topic,
+        content: output,
+        type: options.type ?? 'analysis',
+        confidence: options.confidence ?? 0.8,
+        relatedFiles: options.relatedFiles,
+    };
+}
+/**
+ * Extract key findings from a text summary.
+ */
+export function extractFindings(text, topic) {
+    const findings = [];
+    // Look for bullet points or numbered items
+    const lines = text.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.match(/^[-*•]\s+/) || trimmed.match(/^\d+\.\s+/)) {
+            const content = trimmed.replace(/^[-*•\d.]+\s+/, '');
+            if (content.length > 10) {
+                findings.push({
+                    topic,
+                    content,
+                    type: 'discovery',
+                    confidence: 0.7,
+                });
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=shared-blackboard.js.map