opencode-writer-swarm 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zaxbysauce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# OpenCode Writer Swarm
+# OpenCode-StoryForge
+
+OpenCode-StoryForge is the editorial swarm plugin for OpenCode that orchestrates a curated team of AI agents to draft, research, revise, and polish multi-stage writing projects. Designed with GitHub and npm users in mind, it markets a catchy collaborative workflow, pro-level polishing crew, and clear configuration knobs while still linking down to the technical usage sections below.
+
+## Agents
+
+- **Editor-in-Chief**: Orchestrator, direction setter.
+- **Writer**: Draft creator.
+- **Researcher**: Fact gatherer.
+- **Section Editor**: Structure reviewer.
+- **Copy Editor**: Language polisher and AI slop remover.
+- **Fact Checker**: Verification expert.
+- **Reader Advocate**: Audience representative.
+
+## Usage
+
+## Editor-in-Chief Role
+
+OpenCode surfaces `editor_in_chief` as the primary role inside the UI, so you can pick it from the agent selector just like any other OpenCode plugin. When you kick off the Editor-in-Chief, StoryForge inherits whichever model you selected for that session (the same behavior as `opencode-swarm`), and you can still override the model via `opencode-writer-swarm` config if you need a different fallback.
+
+1. Add the plugin to your `opencode.json`.
+2. Configure models in `~/.config/opencode/opencode-writer-swarm.json` or `.opencode/opencode-writer-swarm.json`.
+3. Invoke `@editor_in_chief` with a writing request.
+
+## Workflow
+
+1. **Brief**: Editor-in-Chief creates a brief.
+2. **Research**: Researcher gathers facts.
+3. **Plan**: Editor-in-Chief creates a content plan.
+4. **Draft**: Writer produces the first draft.
+5. **Review**: Section Editor, Copy Editor, Fact Checker, and Reader Advocate review the draft.
+6. **Polish**: Copy Editor does a final polish.
+7. **Delivery**: Final output saved to `.writer/final/`.
+
+## Configuration
+
+| Setting | Description |
+| --- | --- |
+| `config_validation_enabled` (`CONFIG_VALIDATION_ENABLED`) | Enables the prototype-pollution guard in `deepMerge`. Set to `false` to fall back to the previous behavior. |
+| `FILE_VALIDATION_ENABLED` | Controls symlink/size/depth validation for `.writer` files. Disable to revert to the legacy permissive reader. |
+| `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. |

package/dist/agents/copy-editor.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './types';
+export declare function createCopyEditorAgent(model: string, prompt: string): AgentDefinition;

package/dist/agents/definitions.d.ts

@@ -0,0 +1,2 @@
+import type { AgentTemplate } from './types';
+export declare const AGENT_TEMPLATES: AgentTemplate[];

package/dist/agents/editor-in-chief.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './types';
+export declare function createEditorInChiefAgent(model: string, prompt: string): AgentDefinition;

package/dist/agents/fact-checker.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './types';
+export declare function createFactCheckerAgent(model: string, prompt: string): AgentDefinition;

package/dist/agents/index.d.ts

@@ -0,0 +1,12 @@
+import type { AgentConfig as SDKAgentConfig } from '@opencode-ai/sdk';
+import { type PluginConfig } from '../config';
+import type { AgentDefinition } from './types';
+export type { AgentDefinition } from './types';
+/**
+ * Create all agent definitions with configuration applied
+ */
+export declare function createAgents(config?: PluginConfig): AgentDefinition[];
+/**
+ * Get agent configurations formatted for the OpenCode SDK.
+ */
+export declare function getAgentConfigs(config?: PluginConfig): Record<string, SDKAgentConfig>;

package/dist/agents/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agents/reader-advocate.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './types';
+export declare function createReaderAdvocateAgent(model: string, prompt: string): AgentDefinition;

package/dist/agents/researcher.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './types';
+export declare function createResearcherAgent(model: string, prompt: string): AgentDefinition;

package/dist/agents/section-editor.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './types';
+export declare function createSectionEditorAgent(model: string, prompt: string): AgentDefinition;

package/dist/agents/types.d.ts

@@ -0,0 +1,11 @@
+import type { AgentConfig } from '@opencode-ai/sdk';
+export interface AgentDefinition {
+    name: string;
+    description?: string;
+    config: AgentConfig;
+}
+export interface AgentTemplate {
+    name: string;
+    description: string;
+    defaultTemperature: number;
+}

package/dist/agents/writer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './types';
+export declare function createWriterAgent(model: string, prompt: string): AgentDefinition;

package/dist/config/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_MODELS: Record<string, string>;
+export declare const MAX_FILE_SIZE = 10485760;
+export declare const MAX_DIRECTORY_DEPTH = 10;

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+export * from './constants';
+export * from './loader';
+export * from './schema';

package/dist/config/loader.d.ts

@@ -0,0 +1,49 @@
+import { type PluginConfig } from './schema';
+export declare const MAX_CONFIG_FILE_BYTES = 102400;
+/**
+ * Structured error log entry for config loading failures.
+ */
+export interface ConfigLoadErrorLog {
+    timestamp: string;
+    filePath: string;
+    errorCode: string | null;
+    errorName: string;
+    message: string;
+}
+/**
+ * Log a structured error when config loading fails.
+ * Exported for testing purposes.
+ */
+export declare function logConfigLoadError(filePath: string, error: unknown): void;
+/**
+ * Options for deepMerge function.
+ */
+export interface DeepMergeOptions {
+    enforceKeyFiltering?: boolean;
+}
+/**
+ * Deep merge two objects, with override values taking precedence.
+ * Arrays are replaced, not merged.
+ *
+ * When enforceKeyFiltering is enabled, keys like __proto__, constructor, and prototype
+ * are skipped to prevent prototype pollution attacks.
+ */
+export declare function deepMerge<T>(base?: T, override?: T, options?: DeepMergeOptions): T | undefined;
+/**
+ * Load plugin configuration from user and project config files.
+ *
+ * Config locations:
+ * 1. User config: ~/.config/opencode/opencode-writer-swarm.json
+ * 2. Project config: <directory>/.opencode/opencode-writer-swarm.json
+ *
+ * Project config takes precedence.
+ */
+export declare function loadPluginConfig(directory: string): PluginConfig;
+/**
+ * Load prompt file from prompts/ directory
+ */
+export declare function loadPrompt(name: string): string;
+/**
+ * Load reference file from references/ directory
+ */
+export declare function loadReference(name: string): string;

package/dist/config/loader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/schema.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export declare const AgentOverrideConfigSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AgentOverrideConfig = z.infer<typeof AgentOverrideConfigSchema>;
+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>>>;
+    qa_retry_limit: z.ZodDefault<z.ZodNumber>;
+    file_retry_enabled: z.ZodDefault<z.ZodBoolean>;
+    max_file_operation_retries: z.ZodDefault<z.ZodNumber>;
+    config_validation_enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+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;

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

@@ -0,0 +1,5 @@
+import type { PluginConfig } from '../config';
+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,3 @@
+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;

package/dist/hooks/extractors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/index.d.ts

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

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

@@ -0,0 +1,3 @@
+import type { Hooks } from '@opencode-ai/plugin';
+import type { PluginConfig } from '../config';
+export declare function createSystemEnhancerHook(config: PluginConfig, directory: string): Partial<Hooks>;

package/dist/hooks/utils.d.ts

@@ -0,0 +1,37 @@
+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>;
+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 checkDirectoryDepth(currentDepth: number): void;
+export declare function isSymlink(filePath: string): 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;

package/dist/hooks/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

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