@compilr-dev/sdk 0.1.27 → 0.2.0

package/dist/team/team.d.ts

@@ -0,0 +1,297 @@
+/**
+ * AgentTeam - Multi-agent orchestration
+ *
+ * Manages a team of persistent agents:
+ * - Agent switching ($name prefix)
+ * - Isolated contexts per agent
+ * - Team-level persistence
+ * - Event notifications
+ */
+import type { Agent, AgentConfig } from '@compilr-dev/agents';
+import { TeamAgent } from './team-agent.js';
+import type { TeamAgentConfig, SerializedTeam, TeamEventHandler, AgentRole } from './types.js';
+import type { ModelTier } from '../models/index.js';
+import { SharedContextManager } from './shared-context.js';
+import { ArtifactStore } from './artifacts.js';
+import type { CustomAgentDefinition } from './custom-agents.js';
+import type { ISessionRegistry } from './interfaces.js';
+/**
+ * Configuration for creating an AgentTeam
+ */
+export interface AgentTeamConfig {
+    /**
+     * Team name (for display and persistence)
+     */
+    name?: string;
+    /**
+     * Factory function to create Agent instances
+     * The team uses this to create agents with consistent configuration
+     * @param config - Agent configuration
+     * @param systemPromptAddition - Additional system prompt content
+     * @param useMinimalSystemPrompt - Use minimal system prompt
+     * @param noTools - Skip tool registration
+     * @param toolFilter - Limit which tools this agent can use
+     * @param modelTier - Model tier for this agent (fast/balanced/powerful)
+     */
+    agentFactory: (config: Partial<AgentConfig>, systemPromptAddition?: string, useMinimalSystemPrompt?: boolean, noTools?: boolean, toolFilter?: string[], modelTier?: ModelTier) => Promise<Agent>;
+    /**
+     * Initial agents to add to the team (optional)
+     * If not provided, starts with just the default agent
+     */
+    initialAgents?: TeamAgentConfig[];
+    /**
+     * Event handler for team events
+     */
+    onEvent?: TeamEventHandler;
+    /**
+     * Shared context manager (optional, created if not provided)
+     */
+    sharedContext?: SharedContextManager;
+    /**
+     * Artifact store (optional, created if not provided)
+     */
+    artifactStore?: ArtifactStore;
+    /**
+     * Session registry for cross-terminal collision detection (optional).
+     * CLI provides this via SQLite; desktop/other consumers may omit it.
+     */
+    sessionRegistry?: ISessionRegistry;
+}
+/**
+ * AgentTeam orchestrates multiple persistent agents
+ */
+export declare class AgentTeam {
+    /**
+     * Team name
+     */
+    readonly name: string;
+    /**
+     * Map of agent ID to TeamAgent
+     */
+    private readonly agents;
+    /**
+     * Currently active agent ID
+     */
+    private _activeAgentId;
+    /**
+     * Coordinator agent ID (optional)
+     */
+    private _coordinatorId?;
+    /**
+     * Factory for creating agents
+     */
+    private readonly agentFactory;
+    /**
+     * Event handler
+     */
+    private readonly onEvent?;
+    /**
+     * Shared context manager for cross-agent knowledge sharing
+     */
+    private readonly _sharedContext;
+    /**
+     * Artifact store for team artifacts
+     */
+    private readonly _artifactStore;
+    /**
+     * Optional session registry for collision detection
+     */
+    private readonly _sessionRegistry?;
+    /**
+     * Track handoff source: targetAgentId → sourceAgentId
+     * Used for one-hop prevention (agents that were handed a task
+     * cannot re-hand it off, except back to the coordinator)
+     */
+    private readonly _handedFrom;
+    /**
+     * Creation timestamp
+     */
+    private readonly createdAt;
+    /**
+     * Last updated timestamp
+     */
+    private updatedAt;
+    constructor(config: AgentTeamConfig);
+    /**
+     * Get the currently active agent ID
+     */
+    get activeAgentId(): string;
+    /**
+     * Get the coordinator agent ID (if set)
+     */
+    get coordinatorId(): string | undefined;
+    /**
+     * Get the shared context manager
+     */
+    get sharedContext(): SharedContextManager;
+    /**
+     * Get the artifact store
+     */
+    get artifactStore(): ArtifactStore;
+    /**
+     * Get the currently active TeamAgent
+     */
+    getActive(): TeamAgent;
+    /**
+     * Get the currently active Agent instance
+     * Returns null if not initialized
+     */
+    getActiveAgent(): Agent | null;
+    /**
+     * Get a specific TeamAgent by ID
+     */
+    get(id: string): TeamAgent | undefined;
+    /**
+     * Set the agent instance for the default TeamAgent
+     * Used when the agent is created before the team
+     */
+    setDefaultAgent(agent: Agent): void;
+    /**
+     * Check if an agent exists in the team
+     */
+    has(id: string): boolean;
+    /**
+     * Get all agent IDs
+     */
+    getAgentIds(): string[];
+    /**
+     * Get all TeamAgents
+     */
+    getAll(): TeamAgent[];
+    /**
+     * Get team size (number of agents)
+     */
+    get size(): number;
+    /**
+     * Add a new agent to the team
+     */
+    addAgent(config: TeamAgentConfig): Promise<TeamAgent>;
+    /**
+     * Add an agent from a predefined role
+     * @param role - The predefined role
+     * @param id - Optional custom ID (defaults to role name)
+     * @param modelTier - Optional model tier override (defaults to role's default tier)
+     */
+    addAgentFromRole(role: AgentRole, id?: string, modelTier?: ModelTier): Promise<TeamAgent>;
+    /**
+     * Add a custom agent from a CustomAgentDefinition
+     */
+    addCustomAgent(def: CustomAgentDefinition): Promise<TeamAgent>;
+    /**
+     * Remove an agent from the team
+     */
+    removeAgent(id: string): boolean;
+    /**
+     * Clear conversation history for all agents in the team
+     * Used by /reset command to start fresh
+     */
+    clearAllHistories(): void;
+    /**
+     * Callback for checking in-progress tasks when switching agents
+     * Set by the consumer to provide task counts for warnings
+     */
+    private _getInProgressTasksCallback?;
+    /**
+     * Set the callback for getting in-progress tasks
+     * Used by consumer to integrate with todo list and work items
+     */
+    setInProgressTasksCallback(callback: (agentId: string) => {
+        todos: string[];
+        workItems: string[];
+    }): void;
+    /**
+     * Switch to a different agent
+     */
+    switchTo(id: string): Promise<TeamAgent>;
+    /**
+     * Set the coordinator agent
+     */
+    setCoordinator(id: string | undefined): void;
+    /**
+     * Check if an agent is the coordinator
+     * The default agent is considered coordinator if no explicit coordinator is set.
+     */
+    isCoordinator(id: string): boolean;
+    /**
+     * Check if the active agent is the coordinator
+     * The default agent is considered coordinator if no explicit coordinator is set.
+     */
+    isActiveCoordinator(): boolean;
+    /**
+     * Change an agent's model tier
+     * This updates the tier and reinitializes the agent with the new model.
+     * Conversation history is preserved.
+     *
+     * @param id - The agent ID
+     * @param newTier - The new model tier
+     * @returns The updated TeamAgent
+     */
+    changeAgentTier(id: string, newTier: ModelTier): Promise<TeamAgent>;
+    /**
+     * Initialize all agents (lazy initialization)
+     */
+    initializeAll(): Promise<void>;
+    /**
+     * Initialize only the active agent
+     */
+    initializeActive(): Promise<Agent>;
+    /**
+     * Parse a message for $agent prefix and switch if needed
+     * Returns the message without the prefix and whether a switch occurred
+     */
+    parseAndSwitch(message: string): Promise<{
+        message: string;
+        switched: boolean;
+        agentId: string;
+    }>;
+    /**
+     * Get autocomplete suggestions for $agent prefix
+     */
+    getAgentSuggestions(prefix: string): Array<{
+        id: string;
+        label: string;
+    }>;
+    /**
+     * Record that sourceAgent handed off to targetAgent.
+     * Used for one-hop prevention.
+     */
+    recordHandoff(targetAgentId: string, sourceAgentId: string): void;
+    /**
+     * Check if an agent was handed a task (i.e., is a handoff target).
+     * If true, this agent cannot re-hand off (except back to coordinator).
+     */
+    wasHandedTo(agentId: string): boolean;
+    /**
+     * Get the source agent that handed off to the given agent.
+     */
+    getHandoffSource(agentId: string): string | undefined;
+    /**
+     * Clear handoff tracking for an agent (after it completes its task).
+     */
+    clearHandoffRecord(agentId: string): void;
+    /**
+     * Serialize the team for persistence
+     */
+    serialize(): SerializedTeam;
+    /**
+     * Restore team state from serialized data
+     */
+    static restore(data: SerializedTeam, agentFactory: AgentTeamConfig['agentFactory'], onEvent?: TeamEventHandler, options?: {
+        sharedContext?: SharedContextManager;
+        artifactStore?: ArtifactStore;
+        sessionRegistry?: ISessionRegistry;
+    }): AgentTeam;
+    /**
+     * Emit a team event
+     */
+    private emit;
+    /**
+     * Build and update the team roster in shared context
+     * Called when team composition or active agent changes
+     */
+    updateTeamRoster(): void;
+    /**
+     * Build the team roster from current agents
+     */
+    private buildTeamRoster;
+}