opencode-writer-swarm 1.0.0 → 1.2.0

package/README.md

@@ -42,3 +42,34 @@ OpenCode surfaces `editor_in_chief` as the primary role inside the UI, so you ca
 | `FILE_RETRY_ENABLED` / `WRITER_MAX_RETRIES` | Toggles exponential backoff retries for writer file writes and limits the number of retries. |
 | `LOG_REDACTION_ENABLED` | When `true` (default), startup logs redact keys ending in `_KEY`, `_SECRET`, or `_TOKEN`. Setting to `false` temporarily disables redaction for debugging. |
 | `VERBOSE_INIT` / `LOG_LEVEL=debug` | Emit detailed initialization metadata (agent count, sanitized config keys) during plugin startup. |
+
+## Slash commands
+
+The plugin exposes a `/swarm` command namespace for inspecting and managing the swarm state:
+
+- `/swarm diagnose` – Runs health checks on `.swarm/plan.md`, `.swarm/context.md`, and the plugin config.
+- `/swarm export` – Emits the current plan/context bundle as a JSON snapshot for backups or migration.
+- `/swarm reset --confirm` – Securely deletes `.swarm/plan.md` and `.swarm/context.md` after a confirmation warning, leaving the workspace in a clean state.
+
+Each slash command validates all arguments and file paths before performing I/O, matching the guardrail philosophy outlined below.
+
+## Guardrails & context budget
+
+Guardrails ensure no single session exceeds configured limits. The defaults (exposed under `guardrails` in your config) are:
+
+- `max_tool_calls: 200`
+- `max_duration_minutes: 30`
+- `max_repetitions: 10`
+- `max_consecutive_errors: 5`
+- `warning_threshold: 0.5`
+
+Warnings fire when you cross 50% of a limit (logged as `Guardrail warning: Approaching tool call limit`). When limits are exceeded the guardrail hook throws to halt further tool execution and protect the agent loop.
+
+Context-budget warnings continue to execute through `experimental.chat.system.transform`, ensuring the architect agent receives system-level alerts when plan/context token budgets reach `0.7` (warning) or `0.9` (critical) of the configured window.
+
+## Release 1.2.0
+
+- Slash commands for `/swarm diagnose`, `/swarm export`, and `/swarm reset --confirm`.
+- Guardrail engine enforcing tool-call/duration/repetition/error limits with configurable warning thresholds.
+- Evidence store keeping `.swarm/evidence` shrink-wrapped with retention and guardrail-aware reads.
+- Documentation, tests, and build/typecheck scripts locked in for a full verification phase.

package/dist/commands/diagnose.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handles the /swarm diagnose command.
+ * Performs health checks on swarm state files and configuration.
+ */
+export declare function handleDiagnoseCommand(directory: string, _args: string[]): Promise<string>;

package/dist/commands/export.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handles the /swarm export command.
+ * Exports plan.md and context.md as a portable JSON object.
+ */
+export declare function handleExportCommand(directory: string, _args: string[]): Promise<string>;

package/dist/commands/index.d.ts

@@ -0,0 +1,19 @@
+import { handleDiagnoseCommand } from './diagnose';
+import { handleExportCommand } from './export';
+import { handleResetCommand } from './reset';
+export interface CommandInput {
+    command: string;
+    args?: string[];
+}
+export interface TextPart {
+    type: 'text';
+    text: string;
+}
+export interface CommandOutput {
+    parts: TextPart[];
+}
+export interface SwarmCommandHandler {
+    (input: CommandInput, output: CommandOutput): Promise<void>;
+}
+export declare function createSwarmCommandHandler(directory: string): SwarmCommandHandler;
+export { handleDiagnoseCommand, handleExportCommand, handleResetCommand };

package/dist/commands/reset.d.ts

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

package/dist/config/schema.d.ts

@@ -5,12 +5,72 @@ export declare const AgentOverrideConfigSchema: z.ZodObject<{
     disabled: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type AgentOverrideConfig = z.infer<typeof AgentOverrideConfigSchema>;
+export declare const ContextBudgetConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    warn: z.ZodDefault<z.ZodNumber>;
+    critical: z.ZodDefault<z.ZodNumber>;
+    warn_threshold: z.ZodOptional<z.ZodNumber>;
+    critical_threshold: z.ZodOptional<z.ZodNumber>;
+    max_injection_tokens: z.ZodDefault<z.ZodNumber>;
+    model_limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    target_agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ContextBudgetConfig = z.infer<typeof ContextBudgetConfigSchema>;
+export declare const EvidenceConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    max_age_days: z.ZodDefault<z.ZodNumber>;
+    max_bundles: z.ZodDefault<z.ZodNumber>;
+    auto_archive: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type EvidenceConfig = z.infer<typeof EvidenceConfigSchema>;
+export declare const GuardrailsConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    max_tool_calls: z.ZodDefault<z.ZodNumber>;
+    max_duration_minutes: z.ZodDefault<z.ZodNumber>;
+    max_repetitions: z.ZodDefault<z.ZodNumber>;
+    max_consecutive_errors: z.ZodDefault<z.ZodNumber>;
+    warning_threshold: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type GuardrailsConfig = z.infer<typeof GuardrailsConfigSchema>;
+export declare const HooksConfigSchema: z.ZodObject<{
+    pre_agent: z.ZodOptional<z.ZodString>;
+    post_agent: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HooksConfig = z.infer<typeof HooksConfigSchema>;
 export declare const PluginConfigSchema: z.ZodObject<{
     agents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         model: z.ZodOptional<z.ZodString>;
         temperature: z.ZodOptional<z.ZodNumber>;
         disabled: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
+    context_budget: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        warn: z.ZodDefault<z.ZodNumber>;
+        critical: z.ZodDefault<z.ZodNumber>;
+        warn_threshold: z.ZodOptional<z.ZodNumber>;
+        critical_threshold: z.ZodOptional<z.ZodNumber>;
+        max_injection_tokens: z.ZodDefault<z.ZodNumber>;
+        model_limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        target_agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    evidence: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        max_age_days: z.ZodDefault<z.ZodNumber>;
+        max_bundles: z.ZodDefault<z.ZodNumber>;
+        auto_archive: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    guardrails: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        max_tool_calls: z.ZodDefault<z.ZodNumber>;
+        max_duration_minutes: z.ZodDefault<z.ZodNumber>;
+        max_repetitions: z.ZodDefault<z.ZodNumber>;
+        max_consecutive_errors: z.ZodDefault<z.ZodNumber>;
+        warning_threshold: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    hooks: z.ZodOptional<z.ZodObject<{
+        pre_agent: z.ZodOptional<z.ZodString>;
+        post_agent: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     qa_retry_limit: z.ZodDefault<z.ZodNumber>;
     file_retry_enabled: z.ZodDefault<z.ZodBoolean>;
     max_file_operation_retries: z.ZodDefault<z.ZodNumber>;
@@ -20,3 +80,7 @@ export type PluginConfig = z.infer<typeof PluginConfigSchema>;
 export declare function getFileRetryEnabled(config?: PluginConfig): boolean;
 export declare function getMaxFileRetries(config?: PluginConfig): number;
 export declare function getConfigValidationEnabled(config?: PluginConfig): boolean;
+export declare function getContextBudgetDefaults(): ContextBudgetConfig;
+export declare function getEvidenceDefaults(): EvidenceConfig;
+export declare function getGuardrailsDefaults(): GuardrailsConfig;
+export declare function getHooksDefaults(): HooksConfig;

package/dist/evidence/index.d.ts

@@ -0,0 +1 @@
+export { EvidenceStore, type EvidenceBundle, type EvidenceRecord, type EvidenceType } from './store';

package/dist/evidence/store.d.ts

@@ -0,0 +1,42 @@
+import type { EvidenceConfig } from '../config/schema';
+export type EvidenceType = 'review' | 'test' | 'diff' | 'approval' | 'note';
+export interface EvidenceBundle {
+    id?: string;
+    type: EvidenceType;
+    payload: unknown;
+    created_at?: string;
+}
+export interface EvidenceRecord extends EvidenceBundle {
+    id: string;
+    created_at: string;
+    filename: string;
+}
+export declare class EvidenceStore {
+    private readonly directory;
+    private readonly config;
+    private readonly initPromise;
+    private readonly lockBackoffs;
+    private evidenceRoot;
+    private tmpRoot;
+    private pruneInFlight;
+    private prunePending;
+    private lastPruneEndTime;
+    constructor(directory: string, config: EvidenceConfig);
+    saveEvidence(bundle: EvidenceBundle): Promise<void>;
+    listEvidence(): Promise<EvidenceRecord[]>;
+    pruneStaleBundles(): Promise<void>;
+    private initialize;
+    private normalizeId;
+    private withLock;
+    private acquireLock;
+    private runPruneCycle;
+    private executePruneCycle;
+    private pruneOnce;
+    private scanEvidenceFiles;
+    private readRecord;
+    private cleanupTmpDirectory;
+    private writeWithRetries;
+    private safeUnlink;
+    private resolveRelativePath;
+    private sleep;
+}

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

@@ -0,0 +1,10 @@
+import type { PluginConfig } from '../config';
+type SystemTransformInput = {
+    agent?: unknown;
+    model?: unknown;
+    [other: string]: unknown;
+};
+export declare function createContextBudgetHook(config: PluginConfig, directory: string): Partial<Record<string, (input: SystemTransformInput, output: {
+    system: string[];
+}) => Promise<void>>>;
+export {};

package/dist/hooks/extractors.d.ts

@@ -1,3 +1,24 @@
-export declare function extractCurrentPhase(content: string): string | null;
-export declare function extractIncompleteTasks(content: string): string | null;
-export declare function extractDecisions(content: string, limit?: number): string | null;
+/** Markdown extractors for plan.md and context.md files. Uses AST parsing with LRU caching. */
+import type { Root } from 'mdast';
+/**
+ * Parse markdown content with LRU caching.
+ * Cache entries expire after 5 minutes and are evicted based on entry count and size limits.
+ */
+export declare function parseMarkdownWithCache(content: string): Root;
+/**
+ * Reset the markdown cache and cache stats.
+ * Useful for testing.
+ */
+export declare function resetMarkdownCache(): void;
+/**
+ * Extracts the current phase information from plan content.
+ */
+export declare function extractCurrentPhase(planContent: string): string | null;
+/**
+ * Extracts incomplete tasks (phases) from plan content.
+ */
+export declare function extractIncompleteTasks(planContent: string, maxChars?: number): string | null;
+/**
+ * Extracts decisions section from context content.
+ */
+export declare function extractDecisions(contextContent: string, maxChars?: number): string | null;

package/dist/hooks/guardrails.d.ts

@@ -0,0 +1,22 @@
+import type { GuardrailsConfig } from '../config/schema';
+/** Tool call input structure */
+interface ToolInput {
+    sessionID: string;
+    tool?: string;
+    agent?: string;
+}
+/** Tool call output structure */
+interface ToolOutput {
+    result?: unknown;
+    error?: unknown;
+}
+/**
+ * Create guardrail hooks for tracking and limiting tool usage.
+ * @param config - Guardrails configuration
+ * @returns Object with toolBefore and toolAfter hooks
+ */
+export declare function createGuardrailsHook(config: GuardrailsConfig): {
+    toolBefore: (input: ToolInput) => Promise<void>;
+    toolAfter: (input: ToolInput, output: ToolOutput) => Promise<void>;
+};
+export {};

package/dist/hooks/index.d.ts

@@ -1,4 +1,5 @@
 import { safeHook, composeHandlers } from './utils';
 import { createSystemEnhancerHook } from './system-enhancer';
 import { createDelegationTrackerHook } from './delegation-tracker';
-export { safeHook, composeHandlers, createSystemEnhancerHook, createDelegationTrackerHook, };
+import { createContextBudgetHook } from './context-budget';
+export { safeHook, composeHandlers, createSystemEnhancerHook, createDelegationTrackerHook, createContextBudgetHook, };

package/dist/hooks/utils.d.ts

@@ -3,35 +3,11 @@ export declare function composeHandlers<I, O>(...fns: Array<(input: I, output: O
 declare function isFileValidationEnabled(): boolean;
 declare function getMaxFileBytes(): number;
 declare function getMaxScanDepth(): number;
-export declare function validateWriterPath(directory: string, filename: string): string;
-export declare function checkFileSizeLimit(filePath: string): void;
+export declare function validateWriterPath(directory: string, filename: string): Promise<string>;
+export declare function validateSwarmPath(directory: string, filename: string): Promise<string>;
+export declare function checkFileSizeLimit(filePath: string): Promise<void>;
 export declare function checkDirectoryDepth(currentDepth: number): void;
-export declare function isSymlink(filePath: string): boolean;
+export declare function isSymlink(filePath: string): Promise<boolean>;
 export { getMaxFileBytes, getMaxScanDepth, isFileValidationEnabled };
 export declare function readWriterFileAsync(directory: string, filename: string): Promise<string | null>;
-/**
- * Estimates the number of tokens in a text string.
- *
- * **Formula:** `tokenCount ≈ Math.ceil(characterCount × 0.33)`
- *
- * This is based on the general observation that one token corresponds to roughly
- * 3 characters of English text on average. The multiplier of 0.33 (1/3) provides
- * a conservative upper-bound estimate.
- *
- * **Accuracy:**
- * - Expected variance: approximately ±40%
- * - Actual token counts vary significantly based on:
- *   - Language (non-English text often requires more tokens per character)
- *   - Content type (code, technical terms, vs. natural language)
- *   - Tokenizer model (GPT-3/4, Claude, etc. use different tokenization schemes)
- *   - Presence of special characters, whitespace, and punctuation
- *
- * **Recommendation:**
- * Use this function only for rough budget planning and preliminary size estimates.
- * For precise token counting required for API limits or billing, use the actual
- * tokenizer of the target model (e.g., tiktoken for OpenAI models).
- *
- * @param text - The input string to estimate token count for
- * @returns The estimated number of tokens (rounded up), or 0 for empty/null input
- */
-export declare function estimateTokens(text: string): number;
+export declare function readSwarmFileAsync(directory: string, filename: string): Promise<string | null>;

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import type { Plugin } from '@opencode-ai/plugin';
-import type { AgentConfig as SDKAgentConfig, Config } from '@opencode-ai/sdk';
+import type { AgentConfig as SDKAgentConfig } from '@opencode-ai/sdk';
 import { type PluginConfig } from './config';
+export * from './plan';
 export declare function getSafeConfigKeys(config: PluginConfig): string[];
 export declare function formatStartupLog(agentCount: number, configKeys: string[], directory: string): string;
-type StoryForgeConfig = Config & PluginConfig & {
+export interface PluginInitConfig {
     agent?: Record<string, SDKAgentConfig>;
-};
-export declare function ensureAgentMap(opencodeConfig: StoryForgeConfig, agents: Record<string, SDKAgentConfig>, logger?: (message: string, data?: unknown) => void): StoryForgeConfig;
+}
+export declare function ensureAgentMap(opencodeConfig: PluginInitConfig, agents: Record<string, SDKAgentConfig>, logger?: (message: string, data?: unknown) => void): PluginInitConfig;
 export declare const WriterSwarmPlugin: Plugin;
 export default WriterSwarmPlugin;