@compilr-dev/sdk 0.1.28 → 0.2.1

package/dist/team/artifacts.js

@@ -0,0 +1,279 @@
+/**
+ * ArtifactStore - Storage for team artifacts
+ *
+ * Artifacts are named pieces of work that agents can publish and reference:
+ * - design: Architecture, API specs, data models
+ * - plan: Sprint plans, task breakdowns, timelines
+ * - review: Code reviews, security audits, feedback
+ * - decision: Architectural decisions, trade-off analysis
+ * - note: General notes, meeting summaries
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+const MAX_SUMMARY_LENGTH = 200;
+// =============================================================================
+// Utilities
+// =============================================================================
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + '...';
+}
+// =============================================================================
+// ArtifactStore
+// =============================================================================
+/**
+ * Manages artifact storage and retrieval
+ */
+export class ArtifactStore {
+    artifacts = new Map();
+    nameToId = new Map(); // name -> id lookup
+    updatedAt = new Date();
+    // ---------------------------------------------------------------------------
+    // CRUD Operations
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a new artifact
+     */
+    create(options) {
+        const id = `art-${String(Date.now())}-${Math.random().toString(36).slice(2, 8)}`;
+        // Generate summary if not provided
+        const summary = options.summary ?? this.generateSummary(options.content);
+        const artifact = {
+            id,
+            name: options.name,
+            agent: options.agent,
+            type: options.type,
+            content: options.content,
+            summary,
+            version: 1,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+            mentions: [],
+            referencedBy: [],
+        };
+        this.artifacts.set(id, artifact);
+        this.nameToId.set(options.name.toLowerCase(), id);
+        this.updatedAt = new Date();
+        return artifact;
+    }
+    /**
+     * Get an artifact by ID
+     */
+    get(id) {
+        return this.artifacts.get(id);
+    }
+    /**
+     * Get an artifact by name (case-insensitive)
+     */
+    getByName(name) {
+        const id = this.nameToId.get(name.toLowerCase());
+        if (id) {
+            return this.artifacts.get(id);
+        }
+        return undefined;
+    }
+    /**
+     * Update an artifact
+     */
+    update(id, options) {
+        const artifact = this.artifacts.get(id);
+        if (!artifact) {
+            return undefined;
+        }
+        if (options.content !== undefined) {
+            artifact.content = options.content;
+            // Regenerate summary if content changed and no new summary provided
+            if (options.summary === undefined) {
+                artifact.summary = this.generateSummary(options.content);
+            }
+        }
+        if (options.summary !== undefined) {
+            artifact.summary = options.summary;
+        }
+        if (options.type !== undefined) {
+            artifact.type = options.type;
+        }
+        artifact.version++;
+        artifact.updatedAt = new Date();
+        this.updatedAt = new Date();
+        return artifact;
+    }
+    /**
+     * Delete an artifact
+     */
+    delete(id) {
+        const artifact = this.artifacts.get(id);
+        if (!artifact) {
+            return false;
+        }
+        this.nameToId.delete(artifact.name.toLowerCase());
+        this.artifacts.delete(id);
+        this.updatedAt = new Date();
+        return true;
+    }
+    /**
+     * Rename an artifact
+     */
+    rename(id, newName) {
+        const artifact = this.artifacts.get(id);
+        if (!artifact) {
+            return undefined;
+        }
+        // Update name lookup
+        this.nameToId.delete(artifact.name.toLowerCase());
+        artifact.name = newName;
+        this.nameToId.set(newName.toLowerCase(), id);
+        artifact.updatedAt = new Date();
+        this.updatedAt = new Date();
+        return artifact;
+    }
+    // ---------------------------------------------------------------------------
+    // Query Operations
+    // ---------------------------------------------------------------------------
+    /**
+     * List all artifacts
+     */
+    list() {
+        return Array.from(this.artifacts.values());
+    }
+    /**
+     * List artifacts by agent
+     */
+    listByAgent(agent) {
+        return this.list().filter((a) => a.agent === agent);
+    }
+    /**
+     * List artifacts by type
+     */
+    listByType(type) {
+        return this.list().filter((a) => a.type === type);
+    }
+    /**
+     * Search artifacts by name or content
+     */
+    search(query) {
+        const lowerQuery = query.toLowerCase();
+        return this.list().filter((a) => a.name.toLowerCase().includes(lowerQuery) ||
+            a.content.toLowerCase().includes(lowerQuery) ||
+            a.summary.toLowerCase().includes(lowerQuery));
+    }
+    /**
+     * Get artifact count
+     */
+    get size() {
+        return this.artifacts.size;
+    }
+    /**
+     * Check if an artifact exists by name
+     */
+    has(name) {
+        return this.nameToId.has(name.toLowerCase());
+    }
+    /**
+     * Check if an artifact exists by ID
+     */
+    hasId(id) {
+        return this.artifacts.has(id);
+    }
+    // ---------------------------------------------------------------------------
+    // Summary Generation
+    // ---------------------------------------------------------------------------
+    /**
+     * Generate a summary from content
+     * Simple extraction of first meaningful lines
+     */
+    generateSummary(content) {
+        // Remove markdown headers and get first meaningful content
+        const lines = content
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith('#'));
+        const summary = lines.slice(0, 3).join(' ');
+        if (summary.length > MAX_SUMMARY_LENGTH) {
+            return truncate(summary, MAX_SUMMARY_LENGTH);
+        }
+        return summary || 'No summary available';
+    }
+    // ---------------------------------------------------------------------------
+    // Index for Shared Context
+    // ---------------------------------------------------------------------------
+    /**
+     * Get summaries for shared context injection
+     */
+    getSummaries() {
+        return this.list()
+            .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime())
+            .map((a) => ({
+            id: a.id,
+            name: a.name,
+            agent: a.agent,
+            type: a.type,
+            summary: a.summary,
+            updatedAt: a.updatedAt,
+        }));
+    }
+    // ---------------------------------------------------------------------------
+    // Serialization
+    // ---------------------------------------------------------------------------
+    /**
+     * Serialize all artifacts for external persistence
+     */
+    serialize() {
+        return this.list().map((a) => ({
+            id: a.id,
+            name: a.name,
+            agent: a.agent,
+            type: a.type,
+            content: a.content,
+            summary: a.summary,
+            version: a.version,
+            createdAt: a.createdAt.toISOString(),
+            updatedAt: a.updatedAt.toISOString(),
+            mentions: a.mentions,
+            referencedBy: a.referencedBy,
+        }));
+    }
+    /**
+     * Restore artifacts from serialized data
+     */
+    restore(data) {
+        this.artifacts.clear();
+        this.nameToId.clear();
+        for (const serialized of data) {
+            const artifact = {
+                id: serialized.id,
+                name: serialized.name,
+                agent: serialized.agent,
+                type: serialized.type,
+                content: serialized.content,
+                summary: serialized.summary,
+                version: serialized.version,
+                createdAt: new Date(serialized.createdAt),
+                updatedAt: new Date(serialized.updatedAt),
+                mentions: serialized.mentions ?? [],
+                referencedBy: serialized.referencedBy ?? [],
+            };
+            this.artifacts.set(artifact.id, artifact);
+            this.nameToId.set(artifact.name.toLowerCase(), artifact.id);
+        }
+        if (data.length > 0) {
+            this.updatedAt = new Date(Math.max(...data.map((d) => new Date(d.updatedAt).getTime())));
+        }
+    }
+    /**
+     * Clear all artifacts
+     */
+    clear() {
+        this.artifacts.clear();
+        this.nameToId.clear();
+        this.updatedAt = new Date();
+    }
+    /**
+     * Get the last update timestamp
+     */
+    getLastUpdated() {
+        return this.updatedAt;
+    }
+}

package/dist/team/collision-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Agent ID Collision Prevention
+ *
+ * When multiple terminals work on the same project, they may try to add
+ * agents with the same ID (e.g., both run `/add pm`). This module detects
+ * and resolves such collisions by querying the session registry for agent
+ * IDs already in use by other terminals.
+ */
+/**
+ * Check if an agent ID is in use by another terminal and resolve collisions.
+ * Returns the original ID if available, or a suffixed variant (e.g., "pm_2").
+ */
+export declare function resolveAgentIdCollision(requestedId: string, localTeamIds: string[], globalAgentIds: string[]): {
+    id: string;
+    wasCollision: boolean;
+};

package/dist/team/collision-utils.js

@@ -0,0 +1,28 @@
+/**
+ * Agent ID Collision Prevention
+ *
+ * When multiple terminals work on the same project, they may try to add
+ * agents with the same ID (e.g., both run `/add pm`). This module detects
+ * and resolves such collisions by querying the session registry for agent
+ * IDs already in use by other terminals.
+ */
+import { randomUUID } from 'crypto';
+/**
+ * Check if an agent ID is in use by another terminal and resolve collisions.
+ * Returns the original ID if available, or a suffixed variant (e.g., "pm_2").
+ */
+export function resolveAgentIdCollision(requestedId, localTeamIds, globalAgentIds) {
+    if (!globalAgentIds.includes(requestedId)) {
+        return { id: requestedId, wasCollision: false };
+    }
+    // Try suffixes: pm_2, pm_3, etc.
+    for (let i = 2; i <= 10; i++) {
+        const candidate = `${requestedId}_${String(i)}`;
+        if (!localTeamIds.includes(candidate) && !globalAgentIds.includes(candidate)) {
+            return { id: candidate, wasCollision: true };
+        }
+    }
+    // Fallback: UUID suffix
+    const fallback = `${requestedId}_${randomUUID().slice(0, 4)}`;
+    return { id: fallback, wasCollision: true };
+}

package/dist/team/context-resolver.d.ts

@@ -0,0 +1,97 @@
+/**
+ * ContextResolver - Resolve $agent mentions to actual content
+ *
+ * Resolution strategy:
+ * 1. Check for explicit artifact reference in context hint
+ * 2. Search artifacts by name/content matching context hint
+ * 3. Fall back to recent conversation history
+ *
+ * Token budgets:
+ * - Single mention: 2000 tokens max
+ * - Multiple mentions: 3000 tokens total, split among mentions
+ */
+import type { AgentTeam } from './team.js';
+import type { ArtifactStore } from './artifacts.js';
+import type { ParsedMention } from './mention-parser.js';
+/**
+ * Resolution source type
+ */
+export type ResolutionSource = 'artifact' | 'history' | 'decision' | 'not_found';
+/**
+ * Resolved mention with content
+ */
+export interface ResolvedMention {
+    /** Original mention */
+    mention: ParsedMention;
+    /** Resolution status */
+    resolved: boolean;
+    /** Source of resolution */
+    source: ResolutionSource;
+    /** Source name (artifact name, "recent history", etc.) */
+    sourceName: string;
+    /** Resolved content to inject */
+    content: string;
+    /** Approximate token count */
+    tokenCount: number;
+}
+/**
+ * Options for resolution
+ */
+export interface ResolveOptions {
+    /** Max tokens per mention (default: 2000) */
+    maxTokensPerMention?: number;
+    /** Max total tokens for all mentions (default: 3000) */
+    maxTotalTokens?: number;
+    /** Include artifact content (not just summary) */
+    includeFullArtifact?: boolean;
+    /** Max history messages to search */
+    maxHistoryMessages?: number;
+}
+/**
+ * Resolve mentions to actual content
+ */
+export declare class ContextResolver {
+    private readonly team;
+    private readonly artifactStore;
+    constructor(team: AgentTeam, artifactStore: ArtifactStore);
+    /**
+     * Resolve multiple mentions
+     */
+    resolveAll(mentions: ParsedMention[], options?: ResolveOptions): Map<string, ResolvedMention>;
+    /**
+     * Resolve a single mention
+     */
+    resolveMention(mention: ParsedMention, options?: ResolveOptions): ResolvedMention;
+    /**
+     * Resolve from artifacts
+     */
+    private resolveFromArtifacts;
+    /**
+     * Resolve from conversation history
+     */
+    private resolveFromHistory;
+    /**
+     * Extract relevant content from messages based on context hint
+     */
+    private extractRelevantContent;
+    /**
+     * Format a message for injection
+     */
+    private formatMessage;
+    /**
+     * Format artifact with full content
+     */
+    private formatArtifactFull;
+    /**
+     * Format artifact with summary only
+     */
+    private formatArtifactSummary;
+    /**
+     * Truncate content to approximate token count
+     */
+    private truncateToTokens;
+}
+/**
+ * Build a context map from resolved mentions
+ */
+export declare function buildContextMap(resolved: Map<string, ResolvedMention>): Map<string, string>;