squads-cli 0.4.10 → 0.4.13

package/dist/index.d.ts

@@ -1,15 +1,633 @@
 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;
+}
+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;
+}
 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?: 'opus' | 'sonnet' | 'haiku';
+    /** 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;
+    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>;
+}
+declare function findSquadsDir(): string | null;
+declare function findProjectRoot(): string | null;
+declare function listSquads(squadsDir: string): string[];
+declare function listAgents(squadsDir: string, squadName?: string): Agent[];
+declare function parseSquadFile(filePath: string): Squad;
+declare function loadSquad(squadName: string): Squad | null;
+declare function loadAgentDefinition(agentPath: string): string;
+declare function addGoalToSquad(squadName: string, goal: string): boolean;
+declare function updateGoalInSquad(squadName: string, goalIndex: number, updates: {
+    completed?: boolean;
+    progress?: string;
+}): boolean;
+
+/**
+ * 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;
 }
+/**
+ * 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, version };
+export { type Agent, type CompressionLevel, type CondenserConfig, type CondenserMessage, type CondenserResult, ContextCondenser, ConversationSummarizer, type EffortLevel, FileDeduplicator, type Goal, type Pipeline, type Squad, type SquadContext, type SquadFrontmatter, type ThresholdConfig, TokenPruner, type TokenTracker, addGoalToSquad, createCondenser, createTracker, estimateMessageTokens, estimateTokens, findProjectRoot, findSquadsDir, formatTrackerStatus, getCompressionLevel, listAgents, listSquads, loadAgentDefinition, loadSquad, parseSquadFile, updateGoalInSquad, updateTracker, version };