opencode-swarm 6.19.7 → 6.20.0

package/dist/knowledge/identity.d.ts

@@ -0,0 +1,25 @@
+/** Project Identity Management for opencode-swarm.
+ * Handles creation and retrieval of project identity files.
+ */
+export interface ProjectIdentity {
+    projectHash: string;
+    projectName: string;
+    repoUrl?: string;
+    absolutePath: string;
+    createdAt: string;
+    swarmVersion: string;
+}
+/**
+ * Get identity file path for a project hash.
+ * Path: {platform-config-dir}/projects/{projectHash}/identity.json
+ */
+export declare function resolveIdentityPath(projectHash: string): string;
+/**
+ * Read existing identity.json or return null if it doesn't exist.
+ */
+export declare function readProjectIdentity(projectHash: string): Promise<ProjectIdentity | null>;
+/**
+ * Create or update identity.json for a project.
+ * Uses atomic write pattern (write to temp file, then rename).
+ */
+export declare function writeProjectIdentity(directory: string, projectHash: string, projectName: string): Promise<ProjectIdentity>;

package/dist/knowledge/index.d.ts

@@ -0,0 +1,2 @@
+/** Knowledge system exports for opencode-swarm. */
+export * from './identity.js';

package/dist/output/agent-writer.d.ts

@@ -0,0 +1,27 @@
+export type AgentType = 'architect' | 'coder' | 'reviewer' | 'test_engineer' | 'explorer' | 'sme' | 'critic' | 'docs' | 'designer';
+export type OutputType = 'review' | 'test' | 'research' | 'analysis' | 'summary';
+export interface AgentOutputMetadata {
+    agent: AgentType;
+    type: OutputType;
+    taskId: string;
+    phase: number;
+    timestamp: string;
+    durationMs?: number;
+    success?: boolean;
+}
+/**
+ * Write agent output to persistent storage
+ * Output: .swarm/outputs/phase-N/task-N.M/{agent}-{type}-{timestamp}.md
+ */
+export declare function writeAgentOutput(directory: string, metadata: AgentOutputMetadata, content: string): Promise<string>;
+/**
+ * Read agent output from persistent storage
+ */
+export declare function readAgentOutput(directory: string, phase: number, taskId: string): Promise<{
+    metadata: AgentOutputMetadata;
+    content: string;
+}[]>;
+/**
+ * List all agent outputs for a phase
+ */
+export declare function listAgentOutputs(directory: string, phase?: number): Promise<AgentOutputMetadata[]>;

package/dist/output/index.d.ts

@@ -0,0 +1 @@
+export { type AgentOutputMetadata, type AgentType, listAgentOutputs, type OutputType, readAgentOutput, writeAgentOutput, } from './agent-writer';

package/dist/parallel/dependency-graph.d.ts

@@ -0,0 +1,34 @@
+export interface TaskNode {
+    id: string;
+    phase: number;
+    description: string;
+    depends: string[];
+    dependents: string[];
+    status: 'pending' | 'in_progress' | 'complete' | 'blocked';
+}
+export interface DependencyGraph {
+    tasks: Map<string, TaskNode>;
+    phases: Map<number, string[]>;
+    roots: string[];
+    leaves: string[];
+}
+/**
+ * Parse plan.json and build dependency graph
+ */
+export declare function parseDependencyGraph(planPath: string): DependencyGraph;
+/**
+ * Get tasks that can run in parallel (no unresolved dependencies)
+ */
+export declare function getRunnableTasks(graph: DependencyGraph): string[];
+/**
+ * Check if a task is blocked (has incomplete dependencies)
+ */
+export declare function isTaskBlocked(graph: DependencyGraph, taskId: string): boolean;
+/**
+ * Get execution order (topological sort)
+ */
+export declare function getExecutionOrder(graph: DependencyGraph): string[];
+/**
+ * Find all paths from root to a task
+ */
+export declare function getDependencyChain(graph: DependencyGraph, taskId: string): string[];

package/dist/parallel/file-locks.d.ts

@@ -0,0 +1,33 @@
+export interface FileLock {
+    filePath: string;
+    agent: string;
+    taskId: string;
+    timestamp: string;
+    expiresAt: number;
+}
+/**
+ * Try to acquire a lock on a file
+ */
+export declare function tryAcquireLock(directory: string, filePath: string, agent: string, taskId: string): {
+    acquired: true;
+    lock: FileLock;
+} | {
+    acquired: false;
+    existing?: FileLock;
+};
+/**
+ * Release a lock on a file
+ */
+export declare function releaseLock(directory: string, filePath: string, taskId: string): boolean;
+/**
+ * Check if a file is locked
+ */
+export declare function isLocked(directory: string, filePath: string): FileLock | null;
+/**
+ * Clean up expired locks
+ */
+export declare function cleanupExpiredLocks(directory: string): number;
+/**
+ * List all active locks
+ */
+export declare function listActiveLocks(directory: string): FileLock[];

package/dist/parallel/index.d.ts

@@ -0,0 +1,4 @@
+export { type DependencyGraph, getDependencyChain, getExecutionOrder, getRunnableTasks, isTaskBlocked, parseDependencyGraph, type TaskNode, } from './dependency-graph.js';
+export { cleanupExpiredLocks, type FileLock, isLocked, listActiveLocks, releaseLock, tryAcquireLock, } from './file-locks.js';
+export { extractMetaSummaries, getLatestTaskSummary, indexMetaSummaries, type MetaSummaryEntry, querySummaries, } from './meta-indexer.js';
+export { type ComplexityMetrics, computeComplexity, type ReviewDepth, type ReviewRouting, routeReview, routeReviewForChanges, shouldParallelizeReview, } from './review-router.js';

package/dist/parallel/meta-indexer.d.ts

@@ -0,0 +1,32 @@
+export interface MetaSummaryEntry {
+    timestamp: string;
+    phase?: number;
+    taskId?: string;
+    agent?: string;
+    summary: string;
+    source?: string;
+}
+/**
+ * Extract meta.summary from event JSONL files
+ */
+export declare function extractMetaSummaries(eventsPath: string): MetaSummaryEntry[];
+/**
+ * Index meta summaries to external knowledge store
+ */
+export declare function indexMetaSummaries(directory: string, externalKnowledgeDir?: string): Promise<{
+    indexed: number;
+    path: string;
+}>;
+/**
+ * Query indexed summaries
+ */
+export declare function querySummaries(directory: string, options?: {
+    phase?: number;
+    taskId?: string;
+    agent?: string;
+    since?: string;
+}): MetaSummaryEntry[];
+/**
+ * Get latest summary for a task
+ */
+export declare function getLatestTaskSummary(directory: string, taskId: string): MetaSummaryEntry | undefined;

package/dist/parallel/review-router.d.ts

@@ -0,0 +1,29 @@
+export type ReviewDepth = 'single' | 'double';
+export interface ReviewRouting {
+    reviewerCount: number;
+    testEngineerCount: number;
+    depth: ReviewDepth;
+    reason: string;
+}
+export interface ComplexityMetrics {
+    fileCount: number;
+    functionCount: number;
+    astChangeCount: number;
+    maxFileComplexity: number;
+}
+/**
+ * Compute complexity metrics for a set of files
+ */
+export declare function computeComplexity(directory: string, changedFiles: string[]): Promise<ComplexityMetrics>;
+/**
+ * Determine review routing based on complexity
+ */
+export declare function routeReview(metrics: ComplexityMetrics): ReviewRouting;
+/**
+ * Route review with full analysis
+ */
+export declare function routeReviewForChanges(directory: string, changedFiles: string[]): Promise<ReviewRouting>;
+/**
+ * Check if review should be parallelized
+ */
+export declare function shouldParallelizeReview(routing: ReviewRouting): boolean;

package/dist/services/context-budget-service.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Context Budget Service
+ *
+ * Provides context budget monitoring for swarm sessions.
+ * Tracks token usage across all context components and provides
+ * warnings when approaching budget limits.
+ */
+/**
+ * Context budget report with detailed token breakdown
+ */
+export interface ContextBudgetReport {
+    /** ISO timestamp when the report was generated */
+    timestamp: string;
+    /** Tokens used for the assembled system prompt */
+    systemPromptTokens: number;
+    /** Tokens used for the plan cursor */
+    planCursorTokens: number;
+    /** Tokens used for knowledge entries */
+    knowledgeTokens: number;
+    /** Tokens used for run memory */
+    runMemoryTokens: number;
+    /** Tokens used for handoff content */
+    handoffTokens: number;
+    /** Tokens used for context.md */
+    contextMdTokens: number;
+    /** Total swarm context tokens (sum of all components) */
+    swarmTotalTokens: number;
+    /** Estimated number of turns in this session */
+    estimatedTurnCount: number;
+    /** Estimated total tokens for the session */
+    estimatedSessionTokens: number;
+    /** Budget usage percentage */
+    budgetPct: number;
+    /** Current budget status */
+    status: 'ok' | 'warning' | 'critical';
+    /** Recommendation message if any */
+    recommendation: string | null;
+}
+/**
+ * Configuration for context budget monitoring
+ */
+export interface ContextBudgetConfig {
+    /** Enable or disable budget monitoring */
+    enabled: boolean;
+    /** Maximum token budget (default: 40000) */
+    budgetTokens: number;
+    /** Warning threshold percentage (default: 70) */
+    warningPct: number;
+    /** Critical threshold percentage (default: 90) */
+    criticalPct: number;
+    /** Warning mode: 'once', 'every', or 'interval' */
+    warningMode: 'once' | 'every' | 'interval';
+    /** Interval for warning mode (default: 20 turns) */
+    warningIntervalTurns: number;
+}
+/**
+ * Budget state for tracking warning suppression
+ */
+export interface BudgetState {
+    /** Turn number when warning was last fired */
+    warningFiredAtTurn: number | null;
+    /** Turn number when critical was last fired */
+    criticalFiredAtTurn: number | null;
+    /** Turn number when context was last injected */
+    lastInjectedAtTurn: number | null;
+}
+/**
+ * Default context budget configuration
+ */
+export declare const DEFAULT_CONTEXT_BUDGET_CONFIG: ContextBudgetConfig;
+/**
+ * Estimate token count for text using character-based approximation
+ *
+ * @param text - The text to estimate tokens for
+ * @returns Estimated token count (ceiling of chars / 3.5)
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Get context budget report with detailed token breakdown
+ *
+ * @param directory - The swarm workspace directory
+ * @param assembledSystemPrompt - The fully assembled system prompt
+ * @param config - Budget configuration
+ * @returns Context budget report
+ */
+export declare function getContextBudgetReport(directory: string, assembledSystemPrompt: string, config: ContextBudgetConfig): Promise<ContextBudgetReport>;
+/**
+ * Format budget warning message based on report
+ *
+ * @param report - The context budget report
+ * @param directory - Directory for state persistence (required for suppression logic)
+ * @param config - Budget configuration for warning mode settings
+ * @returns Warning message string or null if suppressed/ok
+ */
+export declare function formatBudgetWarning(report: ContextBudgetReport, directory: string, config: ContextBudgetConfig): Promise<string | null>;
+/**
+ * Get default context budget config
+ *
+ * @returns Default configuration
+ */
+export declare function getDefaultConfig(): ContextBudgetConfig;

package/dist/services/handoff-service.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Handoff Service
+ *
+ * Provides structured handoff data for agent transitions between swarm sessions.
+ * Reads from .swarm files to gather current state for context-efficient handoffs.
+ */
+/**
+ * Pending QA state from agent sessions
+ */
+export interface PendingQA {
+    taskId: string;
+    lastFailure: string | null;
+}
+/**
+ * Delegation chain entry
+ */
+export interface DelegationEntry {
+    from: string;
+    to: string;
+    taskId: string;
+    timestamp: number;
+}
+/**
+ * Delegation state from session snapshot
+ */
+export interface DelegationState {
+    activeChains: string[];
+    delegationDepth: number;
+    pendingHandoffs: string[];
+}
+/**
+ * Structured handoff data for agent transitions
+ */
+export interface HandoffData {
+    /** ISO timestamp when data was generated */
+    generated: string;
+    /** Current phase number or name */
+    currentPhase: string | null;
+    /** Current task ID being worked on */
+    currentTask: string | null;
+    /** List of incomplete task IDs */
+    incompleteTasks: string[];
+    /** Pending QA state */
+    pendingQA: PendingQA | null;
+    /** Active agent name */
+    activeAgent: string | null;
+    /** Recent decisions from context.md */
+    recentDecisions: string[];
+    /** Delegation state */
+    delegationState: DelegationState | null;
+}
+/**
+ * Get handoff data from the swarm directory.
+ * Reads session state, plan, and context to build comprehensive handoff info.
+ */
+export declare function getHandoffData(directory: string): Promise<HandoffData>;
+/**
+ * Format handoff data as terse markdown for LLM consumption.
+ * Targets under 2K tokens for efficient context injection.
+ */
+export declare function formatHandoffMarkdown(data: HandoffData): string;

package/dist/services/index.d.ts

@@ -1,9 +1,11 @@
 export { analyzeDecisionDrift, DEFAULT_DRIFT_CONFIG, type Decision, type DriftAnalysisResult, type DriftAnalyzerConfig, type DriftSeverity, type DriftSignal, extractDecisionsFromContext, findContradictions, formatDriftForContext, } from './decision-drift-analyzer';
 export { applySafeAutoFixes, type ConfigBackup, type ConfigDoctorResult, type ConfigFinding, type ConfigFix, createConfigBackup, type FindingSeverity, getConfigPaths, runConfigDoctor, runConfigDoctorWithFixes, shouldRunOnStartup, writeBackupArtifact, writeDoctorArtifact, } from './config-doctor';
+export { type BudgetState, type ContextBudgetConfig, type ContextBudgetReport, DEFAULT_CONTEXT_BUDGET_CONFIG, estimateTokens, formatBudgetWarning, getContextBudgetReport, getDefaultConfig, } from './context-budget-service';
 export { type DiagnoseData, formatDiagnoseMarkdown, getDiagnoseData, type HealthCheck, handleDiagnoseCommand, } from './diagnose-service';
 export { type EvidenceEntryData, type EvidenceListData, formatEvidenceListMarkdown, formatTaskEvidenceMarkdown, getEvidenceListData, getTaskEvidenceData, getVerdictEmoji, handleEvidenceCommand, type TaskEvidenceData, } from './evidence-service';
 export { buildEvidenceSummary, EVIDENCE_SUMMARY_VERSION, type EvidenceSummaryArtifact, isAutoSummaryEnabled, type PhaseBlocker, type PhaseEvidenceSummary, REQUIRED_EVIDENCE_TYPES, type TaskEvidenceSummary, } from './evidence-summary-service';
 export { type ExportData, formatExportMarkdown, getExportData, handleExportCommand, } from './export-service';
+export { type DelegationState, formatHandoffMarkdown, getHandoffData, type HandoffData, type PendingQA, } from './handoff-service';
 export { formatHistoryMarkdown, getHistoryData, type HistoryData, handleHistoryCommand, type PhaseHistoryData, } from './history-service';
 export { formatPlanMarkdown, getPlanData, handlePlanCommand, type PlanData, } from './plan-service';
 export { createPreflightIntegration, type PreflightIntegrationConfig, runManualPreflight, } from './preflight-integration';

package/dist/services/run-memory.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Run Memory Service
+ *
+ * Provides append-only per-task outcome logging for tracking task execution
+ * results across swarm sessions. Used to avoid repeating known failure patterns.
+ */
+/**
+ * Represents a single task execution outcome entry
+ */
+export interface RunMemoryEntry {
+    /** ISO timestamp when the entry was recorded */
+    timestamp: string;
+    /** Plan.json task ID (e.g. "3.2") */
+    taskId: string;
+    /** SHA256 hash of taskId + sorted file targets, first 8 chars */
+    taskFingerprint: string;
+    /** Which agent executed the task (e.g. "mega_coder") */
+    agent: string;
+    /** Outcome of the task execution */
+    outcome: 'pass' | 'fail' | 'retry' | 'skip';
+    /** 1-indexed attempt number */
+    attemptNumber: number;
+    /** One-line failure reason (only for fail/retry outcomes) */
+    failureReason?: string;
+    /** Files that were modified during this attempt */
+    filesModified?: string[];
+    /** Wall-clock time in milliseconds */
+    durationMs?: number;
+}
+/**
+ * Generate a task fingerprint from taskId and file targets
+ *
+ * @param taskId - The task identifier
+ * @param fileTargets - Array of file paths that were targeted
+ * @returns First 8 characters of SHA256 hash
+ */
+export declare function generateTaskFingerprint(taskId: string, fileTargets: string[]): string;
+/**
+ * Append a task outcome entry to the run memory log
+ *
+ * @param directory - The swarm workspace directory
+ * @param entry - The outcome entry to record
+ */
+export declare function recordOutcome(directory: string, entry: RunMemoryEntry): Promise<void>;
+/**
+ * Get all entries for a specific task ID
+ *
+ * @param directory - The swarm workspace directory
+ * @param taskId - The task identifier to filter by
+ * @returns Array of matching entries
+ */
+export declare function getTaskHistory(directory: string, taskId: string): Promise<RunMemoryEntry[]>;
+/**
+ * Get all failure and retry entries
+ *
+ * @param directory - The swarm workspace directory
+ * @returns Array of fail/retry entries
+ */
+export declare function getFailures(directory: string): Promise<RunMemoryEntry[]>;
+/**
+ * Generate a compact summary of task failures for context injection
+ *
+ * @param directory - The swarm workspace directory
+ * @returns Formatted summary string (≤500 tokens) or null if no failures
+ */
+export declare function getRunMemorySummary(directory: string): Promise<string | null>;

package/dist/skills/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Skill definition with versioning and per-agent overlays
+ */
+export interface AgentOverlay {
+    agent: string;
+    prompt?: string;
+    model?: string;
+}
+export interface SkillDefinition {
+    id: string;
+    name: string;
+    description: string;
+    SKILL_VERSION: number;
+    basePrompt?: string;
+    agents?: AgentOverlay[];
+}
+export declare const skills: SkillDefinition[];
+export declare const AGENT_OVERLAYS: Record<string, AgentOverlay[]>;
+/**
+ * Get skill by ID
+ */
+export declare function getSkill(id: string): SkillDefinition | undefined;
+/**
+ * Get agent overlay for a skill
+ */
+export declare function getAgentOverlay(skillId: string, agent: string): AgentOverlay | undefined;
+/**
+ * Resolve effective prompt for an agent on a skill
+ */
+export declare function resolveAgentPrompt(skillId: string, agent: string, defaultPrompt: string): string;

package/dist/types/delegation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Delegation Envelope Types
+ * Interface for passing delegated tasks between agents
+ */
+export interface DelegationEnvelope {
+    taskId: string;
+    targetAgent: string;
+    action: string;
+    commandType: 'task' | 'slash_command';
+    files: string[];
+    acceptanceCriteria: string[];
+    technicalContext: string;
+    errorStrategy?: 'FAIL_FAST' | 'BEST_EFFORT';
+    platformNotes?: string;
+}
+/**
+ * Validation result types
+ */
+export type EnvelopeValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "6.19.7",
+	"version": "6.20.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",