opencode-swarm 4.1.1 → 4.3.0

package/README.md

@@ -1,8 +1,9 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-4.1.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-4.3.0-blue" alt="Version">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
   <img src="https://img.shields.io/badge/opencode-plugin-purple" alt="OpenCode Plugin">
   <img src="https://img.shields.io/badge/agents-8-orange" alt="Agents">
+  <img src="https://img.shields.io/badge/tests-447-brightgreen" alt="Tests">
 </p>
 
 <h1 align="center">🐝 OpenCode Swarm</h1>
@@ -323,6 +324,31 @@ bunx opencode-swarm install
 
 ---
 
+## What's New in v4.3.0
+
+### 🔧 Hooks Pipeline
+- **`safeHook()`** — Crash-safe wrapper for all hooks. Errors are caught and logged, never crash the plugin.
+- **`composeHandlers()`** — Compose multiple handlers for the same hook type (Plugin API allows only one handler per type).
+
+### 📊 Context Pruning
+- **Token budget tracking** — Estimates context window usage and injects warnings at 70% and 90% thresholds.
+- **Enhanced session compaction** — Guides OpenCode's built-in compaction with plan.md phases and context.md decisions.
+- **System prompt enhancement** — Injects current phase, task, and key decisions to keep agents focused post-compaction.
+
+### ⚡ Slash Commands
+- **`/swarm status`** — Current phase, progress, and agent count.
+- **`/swarm plan [N]`** — View full plan or a specific phase.
+- **`/swarm agents`** — List all registered agents with models and permissions.
+
+### 🤖 Agent Awareness
+- **Activity tracking** — Tool usage tracked per agent via `tool.execute.before/after` hooks. Activity summary flushed to context.md every 20 events.
+- **Delegation tracking** — Active agent per session tracked via `chat.message` hook. Optional delegation chain logging.
+- **Cross-agent context** — System enhancer injects relevant context from other agents' activity into system prompts.
+
+All features are opt-in via configuration. See [Installation Guide](docs/installation.md) for config options.
+
+---
+
 ## Agents
 
 ### 🎯 Orchestrator
@@ -412,6 +438,20 @@ Create `~/.config/opencode/opencode-swarm.json`:
 
 ---
 
+## Testing
+
+```bash
+# Run all tests
+bun test
+
+# Run specific test file
+bun test tests/unit/config/schema.test.ts
+```
+
+447 unit tests across 21 files covering config, tools, agents, hooks, commands, and state. Uses Bun's built-in test runner — zero additional test dependencies.
+
+---
+
 ## Documentation
 
 - [Architecture Deep Dive](docs/architecture.md)

package/dist/commands/agents.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from '../agents';
+export declare function handleAgentsCommand(agents: Record<string, AgentDefinition>): string;

package/dist/commands/index.d.ts

@@ -0,0 +1,15 @@
+import type { AgentDefinition } from '../agents';
+export { handleAgentsCommand } from './agents';
+export { handlePlanCommand } from './plan';
+export { handleStatusCommand } from './status';
+/**
+ * Creates a command.execute.before handler for /swarm commands.
+ * Uses factory pattern to close over directory and agents.
+ */
+export declare function createSwarmCommandHandler(directory: string, agents: Record<string, AgentDefinition>): (input: {
+    command: string;
+    sessionID: string;
+    arguments: string;
+}, output: {
+    parts: unknown[];
+}) => Promise<void>;

package/dist/commands/plan.d.ts

@@ -0,0 +1 @@
+export declare function handlePlanCommand(directory: string, args: string[]): Promise<string>;

package/dist/commands/status.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from '../agents';
+export declare function handleStatusCommand(directory: string, agents: Record<string, AgentDefinition>): Promise<string>;

package/dist/config/loader.d.ts

@@ -1,4 +1,8 @@
 import { type PluginConfig } from './schema';
+/**
+ * Deep merge two objects, with override values taking precedence.
+ */
+export declare function deepMerge<T extends Record<string, unknown>>(base?: T, override?: T): T | undefined;
 /**
  * Load plugin configuration from user and project config files.
  *

package/dist/config/schema.d.ts

@@ -14,6 +14,21 @@ export declare const SwarmConfigSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type SwarmConfig = z.infer<typeof SwarmConfigSchema>;
+export declare const HooksConfigSchema: z.ZodObject<{
+    system_enhancer: z.ZodDefault<z.ZodBoolean>;
+    compaction: z.ZodDefault<z.ZodBoolean>;
+    agent_activity: z.ZodDefault<z.ZodBoolean>;
+    delegation_tracker: z.ZodDefault<z.ZodBoolean>;
+    agent_awareness_max_chars: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type HooksConfig = z.infer<typeof HooksConfigSchema>;
+export declare const ContextBudgetConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    warn_threshold: z.ZodDefault<z.ZodNumber>;
+    critical_threshold: z.ZodDefault<z.ZodNumber>;
+    model_limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>;
+export type ContextBudgetConfig = z.infer<typeof ContextBudgetConfigSchema>;
 export declare const PluginConfigSchema: z.ZodObject<{
     agents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         model: z.ZodOptional<z.ZodString>;
@@ -31,6 +46,19 @@ export declare const PluginConfigSchema: z.ZodObject<{
     max_iterations: z.ZodDefault<z.ZodNumber>;
     qa_retry_limit: z.ZodDefault<z.ZodNumber>;
     inject_phase_reminders: z.ZodDefault<z.ZodBoolean>;
+    hooks: z.ZodOptional<z.ZodObject<{
+        system_enhancer: z.ZodDefault<z.ZodBoolean>;
+        compaction: z.ZodDefault<z.ZodBoolean>;
+        agent_activity: z.ZodDefault<z.ZodBoolean>;
+        delegation_tracker: z.ZodDefault<z.ZodBoolean>;
+        agent_awareness_max_chars: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    context_budget: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        warn_threshold: z.ZodDefault<z.ZodNumber>;
+        critical_threshold: z.ZodDefault<z.ZodNumber>;
+        model_limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PluginConfig = z.infer<typeof PluginConfigSchema>;
-export type { AgentName, QAAgentName, PipelineAgentName, } from './constants';
+export type { AgentName, PipelineAgentName, QAAgentName, } from './constants';

package/dist/hooks/agent-activity.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Agent Activity Tracking Hooks
+ *
+ * Tracks tool usage through tool.execute.before and tool.execute.after hooks.
+ * Records timing, success/failure, and periodically flushes aggregated stats.
+ */
+import type { PluginConfig } from '../config/schema';
+/**
+ * Creates agent activity tracking hooks
+ * @param config Plugin configuration
+ * @param directory Project directory path
+ * @returns Tool before and after hook handlers
+ */
+export declare function createAgentActivityHooks(config: PluginConfig, directory: string): {
+    toolBefore: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        args: unknown;
+    }) => Promise<void>;
+    toolAfter: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        title: string;
+        output: string;
+        metadata: unknown;
+    }) => Promise<void>;
+};
+/**
+ * Flushes activity data to context.md file
+ * Ensures only one flush operation runs at a time
+ * @param directory Project directory path
+ */
+declare function flushActivityToFile(directory: string): Promise<void>;
+export { flushActivityToFile as _flushForTesting };

package/dist/hooks/compaction-customizer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Compaction Customizer Hook
+ *
+ * Enhances session compaction by injecting swarm context from plan.md and context.md.
+ * Adds current phase information and key decisions to the compaction context.
+ */
+import type { PluginConfig } from '../config';
+/**
+ * Creates the experimental.session.compacting hook for compaction customization.
+ */
+export declare function createCompactionCustomizerHook(config: PluginConfig, directory: string): Record<string, unknown>;

package/dist/hooks/context-budget.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Context Budget Tracker Hook
+ *
+ * Estimates token usage across all messages and injects budget warnings
+ * when thresholds are exceeded. Uses experimental.chat.messages.transform
+ * to provide proactive context management guidance to the architect agent.
+ */
+import type { PluginConfig } from '../config';
+interface MessageInfo {
+    role: string;
+    agent?: string;
+    sessionID?: string;
+}
+interface MessagePart {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}
+interface MessageWithParts {
+    info: MessageInfo;
+    parts: MessagePart[];
+}
+/**
+ * Creates the experimental.chat.messages.transform hook for context budget tracking.
+ * Injects warnings when context usage exceeds configured thresholds.
+ * Only operates on messages for the architect agent.
+ */
+export declare function createContextBudgetHandler(config: PluginConfig): (_input: Record<string, never>, _output: {
+    messages?: MessageWithParts[];
+}) => Promise<void>;
+export {};

package/dist/hooks/delegation-tracker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Delegation Tracker Hook
+ *
+ * Tracks agent delegation by monitoring chat.message events with agent fields.
+ * Updates the active agent map and optionally logs delegation chain entries.
+ */
+import type { PluginConfig } from '../config/schema';
+/**
+ * Creates the chat.message hook for delegation tracking.
+ */
+export declare function createDelegationTrackerHook(config: PluginConfig): (input: {
+    sessionID: string;
+    agent?: string;
+}, output: Record<string, unknown>) => Promise<void>;

package/dist/hooks/extractors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Swarm File Extractors
+ *
+ * Pure parsing functions for extracting structured data from .swarm/ files.
+ * Used by system-enhancer and compaction-customizer hooks.
+ */
+/**
+ * Extracts the current phase information from plan content.
+ */
+export declare function extractCurrentPhase(planContent: string): string | null;
+/**
+ * Extracts the first incomplete task from the current IN PROGRESS phase.
+ */
+export declare function extractCurrentTask(planContent: string): string | null;
+/**
+ * Extracts decisions section from context content.
+ */
+export declare function extractDecisions(contextContent: string, maxChars?: number): string | null;
+/**
+ * Extracts incomplete tasks from plan content under the current IN PROGRESS phase.
+ */
+export declare function extractIncompleteTasks(planContent: string, maxChars?: number): string | null;
+/**
+ * Extracts patterns section from context content.
+ */
+export declare function extractPatterns(contextContent: string, maxChars?: number): string | null;

package/dist/hooks/index.d.ts

@@ -1 +1,8 @@
+export { createAgentActivityHooks } from './agent-activity';
+export { createCompactionCustomizerHook } from './compaction-customizer';
+export { createContextBudgetHandler } from './context-budget';
+export { createDelegationTrackerHook } from './delegation-tracker';
+export { extractCurrentPhase, extractCurrentTask, extractDecisions, extractIncompleteTasks, extractPatterns, } from './extractors';
 export { createPipelineTrackerHook } from './pipeline-tracker';
+export { createSystemEnhancerHook } from './system-enhancer';
+export { composeHandlers, estimateTokens, readSwarmFileAsync, safeHook, } from './utils';

package/dist/hooks/pipeline-tracker.d.ts

@@ -29,7 +29,7 @@ interface MessageWithParts {
 export declare function createPipelineTrackerHook(config: PluginConfig): {
     'experimental.chat.messages.transform'?: undefined;
 } | {
-    'experimental.chat.messages.transform': (_input: Record<string, never>, output: {
+    'experimental.chat.messages.transform': (input: Record<string, never>, output: {
         messages?: MessageWithParts[];
     }) => Promise<void>;
 };

package/dist/hooks/system-enhancer.d.ts

@@ -0,0 +1,12 @@
+/**
+ * System Enhancer Hook
+ *
+ * Enhances the system prompt with current phase information from the plan
+ * and cross-agent context from the activity log.
+ * Reads plan.md and injects phase context into the system prompt.
+ */
+import type { PluginConfig } from '../config';
+/**
+ * Creates the experimental.chat.system.transform hook for system enhancement.
+ */
+export declare function createSystemEnhancerHook(config: PluginConfig, directory: string): Record<string, unknown>;

package/dist/hooks/utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared hook utilities for OpenCode Swarm
+ *
+ * This module provides common utilities for working with hooks,
+ * including error handling, handler composition, file I/O, and
+ * token estimation for swarm-related operations.
+ */
+export declare function safeHook<I, O>(fn: (input: I, output: O) => Promise<void>): (input: I, output: O) => Promise<void>;
+export declare function composeHandlers<I, O>(...fns: Array<(input: I, output: O) => Promise<void>>): (input: I, output: O) => Promise<void>;
+export declare function readSwarmFileAsync(directory: string, filename: string): Promise<string | null>;
+export declare function estimateTokens(text: string): number;

package/dist/index.d.ts

@@ -11,5 +11,5 @@ import type { Plugin } from '@opencode-ai/plugin';
  */
 declare const OpenCodeSwarm: Plugin;
 export default OpenCodeSwarm;
-export type { AgentName, PluginConfig, QAAgentName, PipelineAgentName, } from './config';
 export type { AgentDefinition } from './agents';
+export type { AgentName, PipelineAgentName, PluginConfig, QAAgentName, } from './config';