opencode-writer-swarm 1.0.0 → 1.2.1

package/dist/plan/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schema';
+export * from './manager';

package/dist/plan/manager.d.ts

@@ -0,0 +1,63 @@
+import { type PlanDocument, type PlanPhase, type TaskStatus } from './schema';
+/**
+ * Error thrown by PlanManager operations
+ */
+export declare class PlanManagerError extends Error {
+    code: string;
+    cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+/**
+ * Interface for plan management operations
+ */
+export interface PlanManager {
+    /**
+     * Load and parse a plan from file (plan.md or plan.json)
+     * @param filePath - Path to plan file (optional, uses default discovery)
+     * @returns Parsed plan document
+     * @throws PlanManagerError if loading or parsing fails
+     */
+    loadPlan(filePath?: string): Promise<PlanDocument>;
+    /**
+     * Get the current active phase
+     * @returns Current phase or null if no active phase
+     */
+    getCurrentPhase(): PlanPhase | null;
+    /**
+     * Update the status of a specific task
+     * @param taskId - Task identifier
+     * @param status - New status value
+     * @returns true if update succeeded
+     * @throws PlanManagerError if task not found
+     */
+    updateTaskStatus(taskId: string, status: TaskStatus): Promise<boolean>;
+    /**
+     * Get the resolved path to the plan file
+     * @returns Absolute path to plan file
+     */
+    getPlanPath(): string;
+    /**
+     * Get the currently loaded plan document
+     * @returns Current plan or null if not loaded
+     */
+    getPlan(): PlanDocument | null;
+}
+/**
+ * Options for creating a PlanManager instance
+ */
+export interface PlanManagerOptions {
+    /** Base directory for plan discovery */
+    baseDir: string;
+    /** Default plan file name (default: 'plan.json') */
+    defaultPlanName?: string;
+    /** Whether to auto-discover plan.md if plan.json not found */
+    autoDiscoverMarkdown?: boolean;
+}
+/**
+ * Create a new PlanManager instance
+ */
+export declare function createPlanManager(options: PlanManagerOptions): PlanManager;
+/**
+ * Load a plan document from file directly (convenience function)
+ */
+export declare function loadPlanDocument(filePath: string): Promise<PlanDocument>;

package/dist/plan/schema.d.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+/**
+ * Task status values representing the lifecycle of a task
+ */
+export declare const TaskStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    in_progress: "in_progress";
+    completed: "completed";
+    blocked: "blocked";
+    cancelled: "cancelled";
+}>;
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
+/**
+ * Individual task within a phase
+ */
+export declare const PlanTaskSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        in_progress: "in_progress";
+        completed: "completed";
+        blocked: "blocked";
+        cancelled: "cancelled";
+    }>>;
+    assignee: z.ZodOptional<z.ZodString>;
+    depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    acceptance_criteria: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type PlanTask = z.infer<typeof PlanTaskSchema>;
+/**
+ * Phase status values
+ */
+export declare const PhaseStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    in_progress: "in_progress";
+    completed: "completed";
+    blocked: "blocked";
+}>;
+export type PhaseStatus = z.infer<typeof PhaseStatusSchema>;
+/**
+ * A phase containing multiple tasks
+ */
+export declare const PlanPhaseSchema: z.ZodObject<{
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    name: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        in_progress: "in_progress";
+        completed: "completed";
+        blocked: "blocked";
+    }>>;
+    tasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        status: z.ZodDefault<z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            completed: "completed";
+            blocked: "blocked";
+            cancelled: "cancelled";
+        }>>;
+        assignee: z.ZodOptional<z.ZodString>;
+        depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        acceptance_criteria: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    started_at: z.ZodOptional<z.ZodString>;
+    completed_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PlanPhase = z.infer<typeof PlanPhaseSchema>;
+/**
+ * Plan metadata for tracking and versioning
+ */
+export declare const PlanMetadataSchema: z.ZodObject<{
+    created_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    version: z.ZodDefault<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    swarm: z.ZodOptional<z.ZodString>;
+    migration_status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        migrated: "migrated";
+        failed: "failed";
+    }>>;
+}, z.core.$strip>;
+export type PlanMetadata = z.infer<typeof PlanMetadataSchema>;
+/**
+ * Main plan document schema supporting both JSON and Markdown-derived structures
+ */
+export declare const PlanDocumentSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodString>;
+    title: z.ZodString;
+    swarm: z.ZodOptional<z.ZodString>;
+    current_phase: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    phases: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        name: z.ZodString;
+        status: z.ZodDefault<z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            completed: "completed";
+            blocked: "blocked";
+        }>>;
+        tasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            status: z.ZodDefault<z.ZodEnum<{
+                pending: "pending";
+                in_progress: "in_progress";
+                completed: "completed";
+                blocked: "blocked";
+                cancelled: "cancelled";
+            }>>;
+            assignee: z.ZodOptional<z.ZodString>;
+            depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            acceptance_criteria: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        started_at: z.ZodOptional<z.ZodString>;
+        completed_at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        created_at: z.ZodOptional<z.ZodString>;
+        updated_at: z.ZodOptional<z.ZodString>;
+        version: z.ZodDefault<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        swarm: z.ZodOptional<z.ZodString>;
+        migration_status: z.ZodOptional<z.ZodEnum<{
+            pending: "pending";
+            migrated: "migrated";
+            failed: "failed";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PlanDocument = z.infer<typeof PlanDocumentSchema>;
+/**
+ * Validation result for plan documents
+ */
+export interface PlanValidationResult {
+    valid: boolean;
+    errors: z.ZodError | null;
+    data?: PlanDocument;
+}
+/**
+ * Validate a plan document against the schema
+ */
+export declare function validatePlanDocument(data: unknown): PlanValidationResult;
+/**
+ * Default empty plan document
+ */
+export declare function createEmptyPlan(title?: string): PlanDocument;
+/**
+ * Get default values for plan metadata
+ */
+export declare function getPlanMetadataDefaults(): PlanMetadata;

package/dist/state.d.ts

@@ -1,6 +1,5 @@
-/**
- * Shared state module for OpenCode Writer Swarm plugin.
- */
+import type { PluginConfig } from './config/schema';
+/** Shared state for plugin sessions and cache tracking. */
 export interface DelegationEntry {
     from: string;
     to: string;
@@ -11,6 +10,16 @@ export interface CacheStats {
     cacheMisses: number;
     cacheSizeBytes: number;
 }
+/** Guardrail tracking state per session */
+export interface GuardrailSession {
+    toolCalls: number;
+    firstToolAt: number | null;
+    repetitionCount: number;
+    consecutiveErrors: number;
+    lastTool: string | null;
+}
+/** Maximum number of sessions to track before pruning */
+export declare const MAX_SESSIONS = 1000;
 export declare const swarmState: {
     /** Active agent per session — keyed by sessionID */
     activeAgent: Map<string, string>;
@@ -20,5 +29,37 @@ export declare const swarmState: {
     pendingEvents: number;
     /** Cache statistics for markdown AST parsing */
     cacheStats: CacheStats;
+    /** Last successfully loaded config document */
+    lastValidConfig: PluginConfig | null;
+    /** Guardrail tracking per session — keyed by sessionID */
+    guardrails: Map<string, GuardrailSession>;
 };
+/**
+ * Prune the oldest sessions from both Maps.
+ * Map iteration order is insertion order, so the first entries are oldest.
+ * @param count - Number of sessions to prune
+ */
+export declare function pruneOldestSessions(count: number): void;
+/**
+ * Enforce the session limit by pruning if Maps exceed MAX_SESSIONS.
+ * Prunes 10% of sessions when the limit is hit.
+ */
+export declare function enforceSessionLimit(): void;
+/** Clear all session tracking, events, and cache stats. Used between tests and for plugin reinitialization. */
 export declare function resetSwarmState(): void;
+/**
+ * Finalize and clear all swarm state.
+ * Alias for resetSwarmState, signaling end-of-lifecycle cleanup.
+ */
+export declare function disposeSwarmState(): void;
+/**
+ * Get or initialize guardrail session state for a given sessionID.
+ * @param sessionID - The session identifier
+ * @returns The guardrail session state (initializes if missing)
+ */
+export declare function getGuardrailSession(sessionID: string): GuardrailSession;
+/**
+ * Reset guardrail state for a specific session.
+ * @param sessionID - The session identifier to clear
+ */
+export declare function resetGuardrailState(sessionID: string): void;

package/dist/state.test.d.ts

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

package/dist/tools/file-manager.d.ts

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs/promises';
 import { type ToolDefinition } from '@opencode-ai/plugin/tool';
 import { MAX_FILE_SIZE, MAX_DIRECTORY_DEPTH } from '../config/constants';
+import { type PluginConfig } from '../config/schema';
 /**
  * Sleep for a given number of milliseconds
  */
@@ -21,15 +22,15 @@ export declare function writeFileWithRetry(filePath: string, content: string, op
     encoding: BufferEncoding;
 }, writeFn?: typeof fs.writeFile, retryEnabled?: boolean, maxRetries?: number): Promise<void>;
 /**
- * Read a file from the .writer/ directory.
+ * Create a tool to read a file from the .writer/ directory.
  */
-export declare const read_writer_file: ToolDefinition;
+export declare function createReadWriterFile(directory: string): ToolDefinition;
 /**
- * Write content to a file in the .writer/ directory. Overwrites if exists.
+ * Create a tool to write content to a file in the .writer/ directory. Overwrites if exists.
  */
-export declare const write_writer_file: ToolDefinition;
+export declare function createWriteWriterFile(directory: string, config?: PluginConfig): ToolDefinition;
 /**
- * List all files in the .writer/ directory recursively.
+ * Create a tool to list all files in the .writer/ directory recursively.
  */
-export declare const list_writer_files: ToolDefinition;
+export declare function createListWriterFiles(directory: string): ToolDefinition;
 export { MAX_FILE_SIZE, MAX_DIRECTORY_DEPTH };

package/package.json

@@ -1,6 +1,6 @@
 {
- "name": "opencode-writer-swarm",
- "version": "1.0.0",
+"name": "opencode-writer-swarm",
+  "version": "1.2.1",
  "description": "Editorial swarm plugin for OpenCode - professional writing workflow with editor-in-chief, writers, and reviewers",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
@@ -39,14 +39,15 @@
  "dependencies": {
   "@opencode-ai/plugin": "^1.1.53",
   "@opencode-ai/sdk": "^1.1.53",
+  "mdast-util-from-markdown": "^2.0.2",
+  "mdast-util-gfm": "^3.1.0",
   "micromark-extension-gfm": "^3.0.0",
-  "zod": "^4.1.8",
-  "mdast-util-from-markdown": "^1.0.0",
-  "mdast-util-gfm": "^1.0.0",
-  "unist-util-visit": "^4.1.0"
+  "unist-util-visit": "^5.1.0",
+  "zod": "^4.1.8"
  },
  "devDependencies": {
   "@biomejs/biome": "2.3.14",
+  "@types/mdast": "^4.0.4",
   "bun-types": "latest",
   "typescript": "^5.7.3"
  }