squads-cli 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -1,17 +1,745 @@
-declare const version = "0.1.0";
+declare const version: string;
 
+type EffortLevel = 'high' | 'medium' | 'low';
+interface SquadContext {
+    mcp?: string[];
+    skills?: string[];
+    memory?: {
+        load?: string[];
+    };
+    model?: {
+        default?: string;
+        expensive?: string;
+        cheap?: string;
+    };
+    budget?: {
+        daily?: number;
+        weekly?: number;
+        perExecution?: number;
+    };
+    /** Cooldown between executions in seconds */
+    cooldown?: number;
+}
+/**
+ * Resolved skill with path and source information.
+ */
+interface ResolvedSkill {
+    /** Skill name (directory or reference name) */
+    name: string;
+    /** Absolute path to the skill directory */
+    path: string;
+    /** Where the skill was found */
+    source: 'squad-local' | 'project' | 'global';
+}
+interface SquadProviders {
+    /** Default provider for all agents (default: anthropic) */
+    default?: string;
+    /** Provider for vision/image tasks */
+    vision?: string;
+    /** Provider for real-time data access */
+    realtime?: string;
+    /** Provider for high-volume/cheap operations */
+    cheap?: string;
+    /** Custom provider mappings by purpose */
+    [key: string]: string | undefined;
+}
+interface SquadFrontmatter {
+    name?: string;
+    mission?: string;
+    repo?: string;
+    stack?: string;
+    context?: SquadContext;
+    effort?: EffortLevel;
+    /** Multi-LLM provider configuration */
+    providers?: SquadProviders;
+    /** Squad names this squad must wait for before executing (phase ordering) */
+    depends_on?: string[];
+}
 interface Agent {
     name: string;
-    model: string;
-    tools: string[];
-    trigger: 'manual' | 'scheduled' | 'event';
+    role: string;
+    trigger: string;
+    status?: string;
+    filePath?: string;
+    squad?: string;
+    effort?: EffortLevel;
+    /** LLM provider override (from agent file frontmatter) */
+    provider?: string;
+    /** Agent purpose (short description) */
+    purpose?: string;
+    /** Cron schedule for scheduled agents */
+    schedule?: string;
+    /** Output destinations */
+    outputs?: string[];
+}
+interface Pipeline {
+    name: string;
+    agents: string[];
+}
+interface Goal {
+    description: string;
+    completed: boolean;
+    progress?: string;
+    metrics?: string[];
+}
+/**
+ * Routine definition for autonomous scheduled execution.
+ * Defined in SQUAD.md under ### Routines yaml block.
+ */
+interface Routine {
+    /** Unique name for the routine */
+    name: string;
+    /** Cron schedule (e.g., "0 8 * * *" for daily 8am) */
+    schedule: string;
+    /** Agents to run in this batch */
+    agents: string[];
+    /** Model to use (defaults to squad default or sonnet) */
+    model?: string;
+    /** Whether the routine is enabled */
+    enabled?: boolean;
+    /** Priority for execution ordering (lower = higher priority) */
+    priority?: number;
+    /** Minimum cooldown between runs (e.g., "6 hours") */
+    cooldown?: string;
 }
 interface Squad {
     name: string;
+    /** Directory name for file path resolution (e.g., "engineering") */
+    dir: string;
+    mission: string;
     agents: Agent[];
-    mission?: string;
+    pipelines: Pipeline[];
+    triggers: {
+        scheduled: string[];
+        event: string[];
+        manual: string[];
+    };
+    /** Autonomous routines for scheduled batch execution */
+    routines: Routine[];
+    dependencies: string[];
+    outputPath: string;
+    goals: Goal[];
+    effort?: EffortLevel;
+    context?: SquadContext;
+    repo?: string;
+    stack?: string;
+    /** Multi-LLM provider configuration */
+    providers?: SquadProviders;
+    /** Domain this squad operates in */
+    domain?: string;
+    /** Permissions for this squad */
+    permissions?: Record<string, boolean>;
+    /** Raw frontmatter for accessing KPIs and other custom fields */
+    frontmatter?: Record<string, unknown>;
+    /** Squad names this squad must wait for (phase ordering) */
+    depends_on?: string[];
+}
+/**
+ * Resolved execution context with paths and metadata.
+ * Extends SquadContext with resolved paths for MCP, skills, and memory.
+ */
+interface ExecutionContext extends SquadContext {
+    /** Squad name this context belongs to */
+    squadName: string;
+    /** Resolved paths and metadata */
+    resolved: {
+        /** Path to MCP config file to use */
+        mcpConfigPath: string;
+        /** Source of MCP config resolution */
+        mcpSource: 'user-override' | 'generated' | 'fallback' | 'squad-local';
+        /** List of MCP servers in the config */
+        mcpServers: string[];
+        /** Resolved skill directory paths (deprecated, use skills instead) */
+        skillPaths: string[];
+        /** Resolved skills with source information */
+        skills: ResolvedSkill[];
+        /** Resolved memory file paths */
+        memoryPaths: string[];
+    };
+}
+/**
+ * Find the .agents/squads directory by searching current directory and parents.
+ * Searches up to 5 parent directories.
+ * @returns Path to squads directory or null if not found
+ */
+declare function findSquadsDir(): string | null;
+/**
+ * Find the root directory of the squads project (where .agents/ lives).
+ * @returns Path to project root or null if not in a squads project
+ */
+declare function findProjectRoot(): string | null;
+/**
+ * List all squad names in the given squads directory.
+ * Only includes directories containing a SQUAD.md file.
+ * @param squadsDir - Path to the .agents/squads directory
+ * @returns Array of squad directory names
+ */
+declare function listSquads(squadsDir: string): string[];
+/**
+ * List all agents in the squads directory or a specific squad.
+ * Agents are markdown files (excluding SQUAD.md) in squad directories.
+ * @param squadsDir - Path to the .agents/squads directory
+ * @param squadName - Optional squad name to filter agents
+ * @returns Array of Agent objects with basic metadata
+ */
+declare function listAgents(squadsDir: string, squadName?: string): Agent[];
+/**
+ * Parse a SQUAD.md file into a Squad object.
+ * Extracts frontmatter metadata, agents, pipelines, goals, and routines.
+ * @param filePath - Path to the SQUAD.md file
+ * @returns Parsed Squad object with all extracted data
+ */
+declare function parseSquadFile(filePath: string): Squad;
+/**
+ * Load and parse a squad by name.
+ * Convenience function that finds the squads directory and parses the squad file.
+ * @param squadName - Name of the squad directory (e.g., "engineering")
+ * @returns Parsed Squad object or null if not found
+ */
+declare function loadSquad(squadName: string): Squad | null;
+/**
+ * Load raw content of an agent definition file.
+ * @param agentPath - Path to the agent markdown file
+ * @returns Raw file content or empty string if file doesn't exist
+ */
+declare function loadAgentDefinition(agentPath: string): string;
+/**
+ * Add a new goal to a squad's SQUAD.md file.
+ * Creates the Goals section if it doesn't exist.
+ * @param squadName - Name of the squad directory
+ * @param goal - Goal description text
+ * @returns True if goal was added successfully
+ */
+declare function addGoalToSquad(squadName: string, goal: string): boolean;
+/**
+ * Update an existing goal in a squad's SQUAD.md file.
+ * Can mark goal as completed or update progress text.
+ * @param squadName - Name of the squad directory
+ * @param goalIndex - Zero-based index of the goal to update
+ * @param updates - Object with optional completed and progress fields
+ * @returns True if goal was updated successfully
+ */
+declare function updateGoalInSquad(squadName: string, goalIndex: number, updates: {
+    completed?: boolean;
+    progress?: string;
+}): boolean;
+/**
+ * Get all available squad-local skills for a squad.
+ * Scans .agents/squads/<squad>/skills/ directory.
+ */
+declare function getSquadLocalSkills(squadDir: string): ResolvedSkill[];
+/**
+ * Resolve execution context for a squad.
+ *
+ * Takes a Squad object and resolves all context references to actual paths:
+ * - MCP config path (four-tier resolution: squad-local, user-override, generated, fallback)
+ * - Skill directory paths (three-tier: squad-local, project, global)
+ * - Memory file paths
+ *
+ * @param squad - The squad to resolve context for
+ * @param forceRegenerate - Force MCP config regeneration
+ * @returns Resolved execution context with all paths
+ */
+declare function resolveExecutionContext(squad: Squad, forceRegenerate?: boolean): ExecutionContext;
+
+/**
+ * Token estimation and tracking for context compression.
+ *
+ * Uses character-based heuristics for speed (no API calls needed).
+ * ~4 characters per token is a reasonable approximation for English text.
+ */
+declare const RATIOS: {
+    readonly english: 4;
+    readonly code: 3.5;
+    readonly json: 3;
+    readonly mixed: 3.75;
+};
+type ContentType = keyof typeof RATIOS;
+/**
+ * Estimate token count from text content.
+ *
+ * @param text - The text to estimate tokens for
+ * @param type - Content type hint for better accuracy
+ * @returns Estimated token count
+ */
+declare function estimateTokens(text: string, type?: ContentType): number;
+/**
+ * Estimate tokens for a message object (handles different formats).
+ */
+declare function estimateMessageTokens(message: {
+    role?: string;
+    content?: string | Array<{
+        type: string;
+        text?: string;
+    }>;
+}): number;
+/**
+ * Token usage tracker for a session.
+ */
+interface TokenTracker {
+    /** Total tokens used so far */
+    used: number;
+    /** Model's context limit */
+    limit: number;
+    /** Usage as percentage (0-1) */
+    percentage: number;
+    /** Breakdown by category */
+    breakdown: {
+        system: number;
+        user: number;
+        assistant: number;
+        tools: number;
+    };
+}
+/**
+ * Create a new token tracker for a session.
+ *
+ * @param model - Model name to determine context limit
+ * @returns Fresh token tracker
+ */
+declare function createTracker(model?: string): TokenTracker;
+/**
+ * Update tracker with new content.
+ *
+ * @param tracker - Tracker to update (mutated in place)
+ * @param content - Content to add
+ * @param category - Category for breakdown tracking
+ */
+declare function updateTracker(tracker: TokenTracker, content: string, category?: keyof TokenTracker['breakdown']): void;
+/**
+ * Check if compression is needed based on thresholds.
+ */
+type CompressionLevel = 'none' | 'light' | 'medium' | 'heavy';
+interface ThresholdConfig {
+    light: number;
+    medium: number;
+    heavy: number;
+}
+/**
+ * Determine what level of compression is needed.
+ *
+ * @param tracker - Current token tracker state
+ * @param thresholds - Custom thresholds (optional)
+ * @returns Compression level needed
+ */
+declare function getCompressionLevel(tracker: TokenTracker, thresholds?: ThresholdConfig): CompressionLevel;
+/**
+ * Format tracker status for display.
+ */
+declare function formatTrackerStatus(tracker: TokenTracker): string;
+
+/**
+ * File deduplication for context compression.
+ *
+ * Tracks file reads across a conversation and replaces duplicate
+ * reads with concise references to save tokens.
+ *
+ * Based on Cline's approach: keeping only the latest version of each
+ * file prevents LLM confusion during edit operations.
+ */
+/**
+ * Record of a file read in the conversation.
+ */
+interface FileReadRecord {
+    /** File path that was read */
+    path: string;
+    /** Turn index where the read occurred */
+    turnIndex: number;
+    /** Estimated token count of the content */
+    tokenCount: number;
+    /** Hash of content for change detection */
+    contentHash: string;
+}
+/**
+ * Tracks file reads across a conversation for deduplication.
+ */
+declare class FileDeduplicator {
+    /** Map of file path to all reads of that file */
+    private reads;
+    /** Current turn index */
+    private currentTurn;
+    /**
+     * Record a file read.
+     *
+     * @param path - File path that was read
+     * @param content - File content that was read
+     */
+    trackRead(path: string, content: string): void;
+    /**
+     * Advance to next turn.
+     */
+    nextTurn(): void;
+    /**
+     * Get current turn index.
+     */
+    getTurn(): number;
+    /**
+     * Check if a file has been read before.
+     *
+     * @param path - File path to check
+     * @returns Previous read record if exists
+     */
+    getPreviousRead(path: string): FileReadRecord | undefined;
+    /**
+     * Get all files that have been read multiple times.
+     *
+     * @returns Map of path to read count
+     */
+    getDuplicateReads(): Map<string, number>;
+    /**
+     * Calculate potential token savings from deduplication.
+     */
+    getPotentialSavings(): number;
+    /**
+     * Generate a deduplication reference message.
+     *
+     * @param path - File path
+     * @param previousTurn - Turn where file was previously read
+     */
+    static createReference(path: string, previousTurn: number): string;
+    /**
+     * Reset tracker state.
+     */
+    reset(): void;
+    /**
+     * Get statistics for debugging.
+     */
+    getStats(): {
+        filesTracked: number;
+        totalReads: number;
+        duplicateReads: number;
+        potentialSavings: number;
+    };
+}
+
+/**
+ * Token-based pruning for context compression.
+ *
+ * Based on OpenCode's approach: protect recent tool outputs (40K tokens)
+ * while pruning older outputs that exceed the threshold.
+ *
+ * Key insight: Recent context is critical for coherence. Older tool
+ * outputs can be removed entirely without summarization.
+ */
+/**
+ * Configuration for token pruning.
+ */
+interface PruneConfig {
+    /** Tokens to protect from pruning (recent window). Default: 40000 */
+    protectRecent: number;
+    /** Minimum tokens that must be prunable before we prune. Default: 20000 */
+    minimumPrunable: number;
+    /** Tool types that should never be pruned */
+    protectedTools: string[];
+}
+/**
+ * Message structure for pruning.
+ */
+interface PrunableMessage {
+    role: string;
+    content: string | Array<MessagePart>;
+    /** Internal: marks message as prunable */
+    _prunable?: boolean;
+    /** Internal: token count for this message */
+    _tokens?: number;
+}
+interface MessagePart {
+    type: string;
+    text?: string;
+    tool_use_id?: string;
+    name?: string;
+    /** Internal: marks part as pruned */
+    _pruned?: boolean;
+    /** Internal: timestamp when pruned */
+    _prunedAt?: number;
+}
+/**
+ * Token pruner for conversation context.
+ */
+declare class TokenPruner {
+    private config;
+    constructor(config?: Partial<PruneConfig>);
+    /**
+     * Prune messages to reduce token count.
+     *
+     * Strategy:
+     * 1. Scan messages backward from newest to oldest
+     * 2. Accumulate tokens for tool outputs
+     * 3. Mark outputs beyond protection window for pruning
+     * 4. Replace pruned outputs with placeholders
+     *
+     * @param messages - Messages to prune
+     * @returns Pruned messages (new array, originals not mutated)
+     */
+    pruneMessages(messages: PrunableMessage[]): PrunableMessage[];
+    /**
+     * Analyze which messages can be pruned.
+     */
+    private analyzePrunability;
+    /**
+     * Apply pruning to messages before the protection index.
+     */
+    private applyPruning;
+    /**
+     * Create a pruned version of a message.
+     */
+    private createPrunedMessage;
+    /**
+     * Check if a message is a tool result.
+     */
+    private isToolResult;
+    /**
+     * Check if a tool is in the protected list.
+     */
+    private isProtectedTool;
+    /**
+     * Extract tool name from a message.
+     */
+    private getToolName;
+    /**
+     * Get statistics about potential pruning.
+     */
+    getStats(messages: PrunableMessage[]): {
+        totalTokens: number;
+        prunableTokens: number;
+        protectedTokens: number;
+        savingsPercentage: number;
+    };
+}
+
+/**
+ * LLM-based summarization for heavy context compression.
+ *
+ * Based on OpenHands' Context Condenser approach:
+ * - Keep first N events (initial context)
+ * - Keep last M events (recent context)
+ * - Summarize the middle section via LLM
+ *
+ * This is the "last resort" compression - only used when at 95%+ context.
+ */
+/**
+ * Configuration for LLM summarization.
+ */
+interface SummaryConfig {
+    /** Number of messages to preserve from start. Default: 4 */
+    keepFirst: number;
+    /** Number of messages to preserve from end. Default: 20 */
+    keepLast: number;
+    /** Model to use for summarization. Default: 'claude-3-5-haiku-20241022' */
+    model: string;
+    /** Maximum tokens for summary output. Default: 2000 */
+    maxSummaryTokens: number;
+}
+/**
+ * Message structure for summarization.
+ */
+interface SummarizableMessage {
+    role: string;
+    content: string | Array<{
+        type: string;
+        text?: string;
+    }>;
+}
+/**
+ * LLM-based conversation summarizer.
+ */
+declare class ConversationSummarizer {
+    private config;
+    private client;
+    constructor(config?: Partial<SummaryConfig>);
+    /**
+     * Get or create Anthropic client.
+     */
+    private getClient;
+    /**
+     * Summarize messages to reduce token count.
+     *
+     * Strategy:
+     * 1. Keep first N messages (system prompt, initial context)
+     * 2. Keep last M messages (recent context, current task)
+     * 3. Summarize everything in between
+     *
+     * @param messages - Messages to summarize
+     * @returns Summarized messages
+     */
+    summarize(messages: SummarizableMessage[]): Promise<SummarizableMessage[]>;
+    /**
+     * Generate a summary of the middle messages.
+     */
+    private generateSummary;
+    /**
+     * Format messages for the summarization prompt.
+     */
+    private formatMessagesForSummary;
+    /**
+     * Extract text content from a message.
+     */
+    private extractContent;
+    /**
+     * Truncate very long content for summary input.
+     */
+    private truncateContent;
+    /**
+     * Estimate the cost of summarization.
+     *
+     * @param messages - Messages that would be summarized
+     * @returns Estimated cost in USD
+     */
+    estimateCost(messages: SummarizableMessage[]): number;
+    /**
+     * Get statistics about potential summarization.
+     */
+    getStats(messages: SummarizableMessage[]): {
+        totalMessages: number;
+        wouldKeep: number;
+        wouldSummarize: number;
+        estimatedCost: number;
+    };
+}
+
+/**
+ * Context Condenser - Main Pipeline
+ *
+ * Coordinates the three compression strategies:
+ * 1. Deduplication (70% threshold) - Replace duplicate file reads
+ * 2. Pruning (85% threshold) - Remove old tool outputs
+ * 3. Summarization (95% threshold) - LLM-based middle section summary
+ *
+ * Based on patterns from OpenCode, OpenHands, and Cline.
+ */
+
+/**
+ * Configuration for the context condenser.
+ */
+interface CondenserConfig {
+    /** Whether context compression is enabled */
+    enabled: boolean;
+    /** Threshold for light compression (deduplication) */
+    lightThreshold: number;
+    /** Threshold for medium compression (pruning) */
+    mediumThreshold: number;
+    /** Threshold for heavy compression (summarization) */
+    heavyThreshold: number;
+    /** Model context limit */
+    modelLimit: number;
+    /** Model name for tracking */
+    model: string;
+    /** Pruning configuration */
+    pruning: Partial<PruneConfig>;
+    /** Summarization configuration */
+    summarization: Partial<SummaryConfig>;
+}
+/**
+ * Message type for the condenser pipeline.
+ */
+interface CondenserMessage extends PrunableMessage, SummarizableMessage {
+    role: string;
+    content: string | Array<{
+        type: string;
+        text?: string;
+        tool_use_id?: string;
+        name?: string;
+    }>;
+}
+/**
+ * Result of a condense operation.
+ */
+interface CondenserResult {
+    /** Condensed messages */
+    messages: CondenserMessage[];
+    /** Compression level applied */
+    level: CompressionLevel;
+    /** Tokens before compression */
+    tokensBefore: number;
+    /** Tokens after compression */
+    tokensAfter: number;
+    /** Savings percentage */
+    savingsPercentage: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Context Condenser - Main class.
+ */
+declare class ContextCondenser {
+    private config;
+    private tracker;
+    private deduplicator;
+    private pruner;
+    private summarizer;
+    /** Metrics for tracking */
+    private metrics;
+    constructor(config?: Partial<CondenserConfig>);
+    /**
+     * Main entry point - condense messages if needed.
+     *
+     * @param messages - Current conversation messages
+     * @returns Condensed messages and metadata
+     */
+    condense(messages: CondenserMessage[]): Promise<CondenserResult>;
+    /**
+     * Apply light compression (deduplication).
+     */
+    private applyDeduplication;
+    /**
+     * Apply medium compression (pruning).
+     */
+    private applyPruning;
+    /**
+     * Apply heavy compression (summarization).
+     */
+    private applySummarization;
+    /**
+     * Update tracker from messages.
+     */
+    private updateTrackerFromMessages;
+    /**
+     * Create result object.
+     */
+    private createResult;
+    /**
+     * Estimate tokens for messages.
+     */
+    private estimateTokens;
+    /**
+     * Get current tracker status.
+     */
+    getStatus(): string;
+    /**
+     * Get tracker for external monitoring.
+     */
+    getTracker(): TokenTracker;
+    /**
+     * Get metrics.
+     */
+    getMetrics(): typeof this.metrics;
+    /**
+     * Check if compression is needed.
+     */
+    needsCompression(): CompressionLevel;
+    /**
+     * Reset condenser state.
+     */
+    reset(): void;
+    /**
+     * Get file deduplicator for integration with tool layer.
+     */
+    getDeduplicator(): FileDeduplicator;
 }
-declare function loadSquad(path: string): Promise<Squad | null>;
-declare function runAgent(agent: Agent, prompt: string): Promise<string>;
+/**
+ * Create a condenser with squad-specific configuration.
+ */
+declare function createCondenser(squadConfig?: {
+    condenser?: {
+        enabled?: boolean;
+        light_threshold?: number;
+        medium_threshold?: number;
+        heavy_threshold?: number;
+        protect_recent?: number;
+    };
+    model?: {
+        default?: string;
+    };
+}): ContextCondenser;
 
-export { type Agent, type Squad, loadSquad, runAgent, version };
+export { type Agent, type CompressionLevel, type CondenserConfig, type CondenserMessage, type CondenserResult, ContextCondenser, ConversationSummarizer, type EffortLevel, type ExecutionContext, FileDeduplicator, type Goal, type Pipeline, type ResolvedSkill, type Squad, type SquadContext, type SquadFrontmatter, type ThresholdConfig, TokenPruner, type TokenTracker, addGoalToSquad, createCondenser, createTracker, estimateMessageTokens, estimateTokens, findProjectRoot, findSquadsDir, formatTrackerStatus, getCompressionLevel, getSquadLocalSkills, listAgents, listSquads, loadAgentDefinition, loadSquad, parseSquadFile, resolveExecutionContext, updateGoalInSquad, updateTracker, version };