maskweaver 0.9.4 → 0.9.6

package/dist/shared-context/logger.d.ts

@@ -1,41 +1,4 @@
-/**
- * Event Logger
- *
- * Append-only event logging for squad activities.
- * Uses JSONL format for efficient streaming and recovery.
- *
- * @author Kent Beck's Dummy Human
- */
 import type { LogEvent, LogEventInput } from "./types.js";
 import type { Session } from "./session.js";
-/**
- * Append an event to a squad's log.
- * Automatically adds a timestamp to the event.
- *
- * @param session - The parent session
- * @param squadId - ID of the squad to log to
- * @param event - Event data (without timestamp)
- *
- * @example
- * await logEvent(session, "squad-a1b2c3d4", {
- *   type: "task_assigned",
- *   taskId: "task-001",
- *   assignee: "worker-1",
- *   description: "Implement login form"
- * });
- */
 export declare function logEvent(session: Session, squadId: string, event: LogEventInput): Promise<void>;
-/**
- * Read all events from a squad's log.
- * Returns an empty array if the log doesn't exist.
- *
- * @param session - The parent session
- * @param squadId - ID of the squad to read from
- * @returns Array of log events in chronological order
- *
- * @example
- * const events = await readLog(session, "squad-a1b2c3d4");
- * const completedTasks = events.filter(e => e.type === "task_completed");
- * console.log(`Completed tasks: ${completedTasks.length}`);
- */
 export declare function readLog(session: Session, squadId: string): Promise<LogEvent[]>;

package/dist/shared-context/logger.js

@@ -1,31 +1,4 @@
-/**
- * Event Logger
- *
- * Append-only event logging for squad activities.
- * Uses JSONL format for efficient streaming and recovery.
- *
- * @author Kent Beck's Dummy Human
- */
 import { readFile } from "fs/promises";
-// ============================================================================
-// Event Logging
-// ============================================================================
-/**
- * Append an event to a squad's log.
- * Automatically adds a timestamp to the event.
- *
- * @param session - The parent session
- * @param squadId - ID of the squad to log to
- * @param event - Event data (without timestamp)
- *
- * @example
- * await logEvent(session, "squad-a1b2c3d4", {
- *   type: "task_assigned",
- *   taskId: "task-001",
- *   assignee: "worker-1",
- *   description: "Implement login form"
- * });
- */
 export async function logEvent(session, squadId, event) {
     const logPath = `${session.sessionPath}/squads/${squadId}/log.jsonl`;
     const fullEvent = {
@@ -34,19 +7,6 @@ export async function logEvent(session, squadId, event) {
     };
     await session.storage.append(logPath, JSON.stringify(fullEvent));
 }
-/**
- * Read all events from a squad's log.
- * Returns an empty array if the log doesn't exist.
- *
- * @param session - The parent session
- * @param squadId - ID of the squad to read from
- * @returns Array of log events in chronological order
- *
- * @example
- * const events = await readLog(session, "squad-a1b2c3d4");
- * const completedTasks = events.filter(e => e.type === "task_completed");
- * console.log(`Completed tasks: ${completedTasks.length}`);
- */
 export async function readLog(session, squadId) {
     const logPath = `${session.sessionPath}/squads/${squadId}/log.jsonl`;
     const fullPath = session.storage.getFullPath(logPath);
@@ -58,7 +18,6 @@ export async function readLog(session, squadId) {
             .map((line) => JSON.parse(line));
     }
     catch {
-        // Log doesn't exist yet - return empty array
         return [];
     }
 }

package/dist/shared-context/parallel-executor.d.ts

@@ -1,11 +1,3 @@
-/**
- * Parallel Execution Engine
- *
- * Executes task waves in parallel using DAG analysis and git worktrees.
- * Each wave contains independent tasks that can run concurrently.
- *
- * @author Jeff Dean's Dummy Human
- */
 import type { Session } from './session.js';
 import type { ExecutionWave, DAGAnalysis } from './dag.js';
 export interface ParallelExecutionPlan {
@@ -26,58 +18,12 @@ export interface WaveExecutionResult {
     allSucceeded: boolean;
 }
 export interface ParallelExecutionOptions {
-    /** Maximum concurrent tasks per wave (default: LIMITS.maxWorkersPerSquad) */
     maxConcurrency?: number;
-    /** Whether to use git worktrees for isolation (default: true) */
     useWorktrees?: boolean;
-    /** Whether to abort remaining tasks on first failure (default: false) */
     failFast?: boolean;
-    /** Callback when a task starts */
     onTaskStart?: (taskId: string, worktreePath?: string) => void;
-    /** Callback when a task completes */
     onTaskComplete?: (taskId: string, success: boolean, error?: string) => void;
-    /** Callback when a wave completes */
     onWaveComplete?: (waveIndex: number, results: WaveExecutionResult) => void;
 }
-/**
- * Create a parallel execution plan from squad tasks.
- * Analyzes dependencies and groups into waves.
- * @param session - The current session object.
- * @param squadId - The ID of the squad to create the plan for.
- * @returns A promise that resolves to the ParallelExecutionPlan.
- * @throws {ValidationError} If DAG analysis fails (e.g., cycle detected).
- * @example
- * import { createExecutionPlan } from './parallel-executor.ts';
- * import { Session } from './types.ts';
- * // Assume 'mockSession' and 'squad-abc' exist
- * const plan = await createExecutionPlan(mockSession, 'squad-abc');
- * console.log(plan.waves.length);
- */
 export declare function createExecutionPlan(session: Session, squadId: string): Promise<ParallelExecutionPlan>;
-/**
- * Execute a single wave of tasks in parallel.
- * - Creates worktrees for each task (if useWorktrees=true)
- * - Dispatches tasks concurrently
- * - Waits for all to complete
- * - Cleans up worktrees
- * - Returns aggregated results
- * @param session - The current session object.
- * @param squadId - The ID of the squad.
- * @param wave - The ExecutionWave to execute.
- * @param executor - A function that takes a taskId and worktreePath, and returns a promise resolving to true for success, false for failure.
- * @param options - Optional execution options.
- * @returns A promise that resolves to the WaveExecutionResult.
- * @example
- * import { executeWave } from './parallel-executor.ts';
- * import { Session, TaskState } from './types.ts';
- * // Assume 'mockSession', 'squad-abc', 'mockWave' exist
- * // mockExecutor would simulate running a task
- * const mockExecutor = async (taskId: string, worktreePath?: string) => {
- *   console.log(`Executing ${taskId} in ${worktreePath || 'main repo'}`);
- *   await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate work
- *   return Math.random() > 0.1; // 90% success rate
- * };
- * const result = await executeWave(mockSession, 'squad-abc', mockWave, mockExecutor);
- * console.log(result.allSucceeded);
- */
 export declare function executeWave(session: Session, squadId: string, wave: ExecutionWave, executor: (taskId: string, worktreePath?: string) => Promise<boolean>, options?: ParallelExecutionOptions): Promise<WaveExecutionResult>;

package/dist/shared-context/parallel-executor.js

@@ -1,29 +1,7 @@
-/**
- * Parallel Execution Engine
- *
- * Executes task waves in parallel using DAG analysis and git worktrees.
- * Each wave contains independent tasks that can run concurrently.
- *
- * @author Jeff Dean's Dummy Human
- */
 import { LIMITS } from './types.js';
 import { buildDAG } from './dag.js';
 import { createWorktreeManager } from './worktree.js';
 import { getSquad, updateSquadState } from './squad.js';
-/**
- * Create a parallel execution plan from squad tasks.
- * Analyzes dependencies and groups into waves.
- * @param session - The current session object.
- * @param squadId - The ID of the squad to create the plan for.
- * @returns A promise that resolves to the ParallelExecutionPlan.
- * @throws {ValidationError} If DAG analysis fails (e.g., cycle detected).
- * @example
- * import { createExecutionPlan } from './parallel-executor.ts';
- * import { Session } from './types.ts';
- * // Assume 'mockSession' and 'squad-abc' exist
- * const plan = await createExecutionPlan(mockSession, 'squad-abc');
- * console.log(plan.waves.length);
- */
 export async function createExecutionPlan(session, squadId) {
     const squad = await getSquad(session, squadId);
     if (!squad) {
@@ -37,32 +15,6 @@ export async function createExecutionPlan(session, squadId) {
         estimatedParallelism: dag.parallelismFactor,
     };
 }
-/**
- * Execute a single wave of tasks in parallel.
- * - Creates worktrees for each task (if useWorktrees=true)
- * - Dispatches tasks concurrently
- * - Waits for all to complete
- * - Cleans up worktrees
- * - Returns aggregated results
- * @param session - The current session object.
- * @param squadId - The ID of the squad.
- * @param wave - The ExecutionWave to execute.
- * @param executor - A function that takes a taskId and worktreePath, and returns a promise resolving to true for success, false for failure.
- * @param options - Optional execution options.
- * @returns A promise that resolves to the WaveExecutionResult.
- * @example
- * import { executeWave } from './parallel-executor.ts';
- * import { Session, TaskState } from './types.ts';
- * // Assume 'mockSession', 'squad-abc', 'mockWave' exist
- * // mockExecutor would simulate running a task
- * const mockExecutor = async (taskId: string, worktreePath?: string) => {
- *   console.log(`Executing ${taskId} in ${worktreePath || 'main repo'}`);
- *   await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate work
- *   return Math.random() > 0.1; // 90% success rate
- * };
- * const result = await executeWave(mockSession, 'squad-abc', mockWave, mockExecutor);
- * console.log(result.allSucceeded);
- */
 export async function executeWave(session, squadId, wave, executor, options) {
     const { maxConcurrency = LIMITS.maxWorkersPerSquad, useWorktrees = true, failFast = false, onTaskStart, onTaskComplete, onWaveComplete, } = options || {};
     const squad = await getSquad(session, squadId);
@@ -70,7 +22,7 @@ export async function executeWave(session, squadId, wave, executor, options) {
         throw new Error(`Squad with ID ${squadId} not found.`);
     }
     const worktreeManager = useWorktrees
-        ? createWorktreeManager({ repoRoot: session.sessionPath }) // Assuming sessionPath is repoRoot
+        ? createWorktreeManager({ repoRoot: session.sessionPath })
         : undefined;
     const waveResults = [];
     let allSucceeded = true;
@@ -113,21 +65,19 @@ export async function executeWave(session, squadId, wave, executor, options) {
         }
         finally {
             const endTime = process.hrtime.bigint();
-            const duration = Number(endTime - startTime) / 1_000_000; // Convert to milliseconds
+            const duration = Number(endTime - startTime) / 1_000_000;
             waveResults.push({ taskId, success, worktreePath, duration, error });
             if (!success) {
                 allSucceeded = false;
             }
             onTaskComplete?.(taskId, success, error);
-            // Update task status in squad
             const taskIndex = squad.state.tasks.findIndex(t => t.taskId === taskId);
             if (taskIndex !== -1) {
                 squad.state.tasks[taskIndex].status = success ? 'completed' : 'failed';
                 squad.state.tasks[taskIndex].completedAt = new Date().toISOString();
-                squad.state.tasks[taskIndex].result = { success, error }; // Store basic result
-                await updateSquadState(session, squad.state.squadId, squad.state); // Persist updated squad state
+                squad.state.tasks[taskIndex].result = { success, error };
+                await updateSquadState(session, squad.state.squadId, squad.state);
             }
-            // Clean up worktree
             if (useWorktrees && worktreeManager) {
                 try {
                     await worktreeManager.remove(taskId);
@@ -137,12 +87,10 @@ export async function executeWave(session, squadId, wave, executor, options) {
                 }
             }
         }
-        // Continue executing next task if not aborted
         if (!abortController?.signal.aborted && taskQueue.length > 0) {
             runningTasks.push(executeNextTask());
         }
     };
-    // Start initial tasks up to maxConcurrency
     for (let i = 0; i < Math.min(maxConcurrency, tasksToExecute.length); i++) {
         runningTasks.push(executeNextTask());
     }

package/dist/shared-context/session.d.ts

@@ -1,73 +1,17 @@
-/**
- * Session Management
- *
- * Creates and manages shared context sessions for multi-agent collaboration.
- * A session is the top-level container that holds squads and their shared state.
- *
- * @author Kent Beck's Dummy Human
- */
 import type { Manifest } from "./types.js";
 import type { StorageAdapter } from "./storage.js";
-/**
- * Options for creating a new collaboration session.
- */
 export interface CreateSessionOptions {
-    /** The high-level goal for this session */
     goal: string;
-    /** Agent ID of the session creator */
     createdBy: string;
-    /** Optional resource constraints */
     constraints?: {
-        /** Maximum duration (e.g., "1h", "30m") */
         timeout?: string;
-        /** Maximum token budget across all squads */
         tokenBudget?: number;
     };
 }
-/**
- * Represents an active collaboration session.
- * Contains the manifest, storage adapter, and path information.
- */
 export interface Session {
-    /** Session metadata and configuration */
     manifest: Manifest;
-    /** Storage adapter for persisting session data */
     storage: StorageAdapter;
-    /** Relative path to session directory */
     sessionPath: string;
 }
-/**
- * Create a new collaboration session with the specified goal.
- * Initializes the directory structure and persists the manifest.
- *
- * @param storage - Storage adapter for persistence
- * @param options - Session configuration options
- * @returns The created session with manifest and storage
- *
- * @example
- * const storage = new FileStorageAdapter("/data");
- * const session = await createSession(storage, {
- *   goal: "Implement OAuth login feature",
- *   createdBy: "operator-agent",
- *   constraints: { timeout: "2h", tokenBudget: 100000 }
- * });
- * console.log(session.manifest.sessionId);
- */
 export declare function createSession(storage: StorageAdapter, options: CreateSessionOptions): Promise<Session>;
-/**
- * Load an existing session by its ID.
- * Returns null if the session doesn't exist.
- * Validates manifest data at system boundary.
- *
- * @param storage - Storage adapter to read from
- * @param sessionId - UUID of the session to load
- * @returns The session if found, null otherwise
- * @throws ValidationError if manifest data is corrupted
- *
- * @example
- * const session = await loadSession(storage, "550e8400-e29b-41d4-a716-446655440000");
- * if (session) {
- *   console.log(`Loaded session: ${session.manifest.goal}`);
- * }
- */
 export declare function loadSession(storage: StorageAdapter, sessionId: string): Promise<Session | null>;

package/dist/shared-context/session.js

@@ -1,34 +1,6 @@
-/**
- * Session Management
- *
- * Creates and manages shared context sessions for multi-agent collaboration.
- * A session is the top-level container that holds squads and their shared state.
- *
- * @author Kent Beck's Dummy Human
- */
 import { randomUUID } from "crypto";
 import { validateManifest } from "./types.js";
 import { ValidationError } from "../shared/errors.js";
-// ============================================================================
-// Session Operations
-// ============================================================================
-/**
- * Create a new collaboration session with the specified goal.
- * Initializes the directory structure and persists the manifest.
- *
- * @param storage - Storage adapter for persistence
- * @param options - Session configuration options
- * @returns The created session with manifest and storage
- *
- * @example
- * const storage = new FileStorageAdapter("/data");
- * const session = await createSession(storage, {
- *   goal: "Implement OAuth login feature",
- *   createdBy: "operator-agent",
- *   constraints: { timeout: "2h", tokenBudget: 100000 }
- * });
- * console.log(session.manifest.sessionId);
- */
 export async function createSession(storage, options) {
     const sessionId = randomUUID();
     const sessionPath = `shared/${sessionId}`;
@@ -41,36 +13,17 @@ export async function createSession(storage, options) {
         squads: [],
         constraints: options.constraints,
     };
-    // Create directory structure
     await storage.ensureDir(sessionPath);
     await storage.ensureDir(`${sessionPath}/events`);
     await storage.ensureDir(`${sessionPath}/squads`);
-    // Persist manifest
     await storage.write(`${sessionPath}/manifest.json`, manifest);
     return { manifest, storage, sessionPath };
 }
-/**
- * Load an existing session by its ID.
- * Returns null if the session doesn't exist.
- * Validates manifest data at system boundary.
- *
- * @param storage - Storage adapter to read from
- * @param sessionId - UUID of the session to load
- * @returns The session if found, null otherwise
- * @throws ValidationError if manifest data is corrupted
- *
- * @example
- * const session = await loadSession(storage, "550e8400-e29b-41d4-a716-446655440000");
- * if (session) {
- *   console.log(`Loaded session: ${session.manifest.goal}`);
- * }
- */
 export async function loadSession(storage, sessionId) {
     const sessionPath = `shared/${sessionId}`;
     const rawManifest = await storage.read(`${sessionPath}/manifest.json`);
     if (!rawManifest)
         return null;
-    // 경계에서 검증 - Parse, don't validate
     try {
         const manifest = validateManifest(rawManifest);
         return { manifest, storage, sessionPath };

package/dist/shared-context/squad.d.ts

@@ -1,92 +1,24 @@
-/**
- * Squad Management
- *
- * Squads are work units within a session, each with their own mission,
- * constraints, and set of tasks. This module handles squad lifecycle.
- *
- * @author Kent Beck's Dummy Human
- */
 import type { SquadSpec, SquadState } from "./types.js";
 import type { Session } from "./session.js";
-/**
- * Options for creating a new squad within a session.
- */
 export interface CreateSquadOptions {
-    /** The squad's mission objective */
     mission: string;
-    /** Agent ID of the squad operator */
     operator: string;
-    /** Optional resource constraints for the squad */
     constraints?: {
-        /** Maximum duration (e.g., "1h", "30m") */
         timeout?: string;
-        /** Maximum token budget for this squad */
         tokenBudget?: number;
-        /** Maximum number of worker agents */
         maxWorkers?: number;
     };
-    /** File/directory scope for the squad's work */
     scope?: {
-        /** Files the squad can modify */
         files?: string[];
-        /** Directories the squad can access */
         directories?: string[];
     };
 }
-/**
- * Create a new squad within a session.
- * A squad is a unit of work with its own mission and constraints.
- *
- * @param session - The parent session
- * @param options - Squad configuration options
- * @returns The created squad's spec and initial state
- * @throws {ValidationError} If session has reached max squad limit
- *
- * @example
- * const { spec, state } = await createSquad(session, {
- *   mission: "Implement user authentication",
- *   operator: "auth-operator",
- *   constraints: { maxWorkers: 3 },
- *   scope: { directories: ["src/auth"] }
- * });
- */
 export declare function createSquad(session: Session, options: CreateSquadOptions): Promise<{
     spec: SquadSpec;
     state: SquadState;
 }>;
-/**
- * Retrieve a squad's specification and current state.
- * Validates data at system boundary.
- *
- * @param session - The parent session
- * @param squadId - ID of the squad to retrieve
- * @returns Squad spec and state, or null if not found
- * @throws ValidationError if data is corrupted
- *
- * @example
- * const squad = await getSquad(session, "squad-a1b2c3d4");
- * if (squad) {
- *   console.log(`Squad status: ${squad.state.status}`);
- * }
- */
 export declare function getSquad(session: Session, squadId: string): Promise<{
     spec: SquadSpec;
     state: SquadState;
 } | null>;
-/**
- * Update a squad's state with partial changes.
- * Automatically updates the `updatedAt` timestamp.
- *
- * @param session - The parent session
- * @param squadId - ID of the squad to update
- * @param updates - Partial state updates to apply
- * @returns The new state after update
- * @throws {StorageError} If the squad doesn't exist
- *
- * @example
- * const newState = await updateSquadState(session, "squad-a1b2c3d4", {
- *   status: "active",
- *   progress: 50
- * });
- */
 export declare function updateSquadState(session: Session, squadId: string, updates: Partial<SquadState>): Promise<SquadState>;

package/dist/shared-context/squad.js

@@ -1,36 +1,7 @@
-/**
- * Squad Management
- *
- * Squads are work units within a session, each with their own mission,
- * constraints, and set of tasks. This module handles squad lifecycle.
- *
- * @author Kent Beck's Dummy Human
- */
 import { randomUUID } from "crypto";
 import { LIMITS, validateSquadSpec, validateSquadState } from "./types.js";
 import { StorageError, ValidationError } from "../shared/errors.js";
-// ============================================================================
-// Squad Operations
-// ============================================================================
-/**
- * Create a new squad within a session.
- * A squad is a unit of work with its own mission and constraints.
- *
- * @param session - The parent session
- * @param options - Squad configuration options
- * @returns The created squad's spec and initial state
- * @throws {ValidationError} If session has reached max squad limit
- *
- * @example
- * const { spec, state } = await createSquad(session, {
- *   mission: "Implement user authentication",
- *   operator: "auth-operator",
- *   constraints: { maxWorkers: 3 },
- *   scope: { directories: ["src/auth"] }
- * });
- */
 export async function createSquad(session, options) {
-    // Enforce squad limit
     if (session.manifest.squads.length >= LIMITS.maxSquadsPerSession) {
         throw new ValidationError("Maximum squads per session exceeded", {
             limit: LIMITS.maxSquadsPerSession,
@@ -60,38 +31,20 @@ export async function createSquad(session, options) {
         sharedContext: {},
         updatedAt: new Date().toISOString(),
     };
-    // Create directory structure and persist data
     await session.storage.ensureDir(squadPath);
     await session.storage.ensureDir(`${squadPath}/scratch`);
     await session.storage.write(`${squadPath}/spec.json`, spec);
     await session.storage.write(`${squadPath}/state.json`, state);
-    // Update session manifest with new squad
     session.manifest.squads.push(squadId);
     await session.storage.write(`${session.sessionPath}/manifest.json`, session.manifest);
     return { spec, state };
 }
-/**
- * Retrieve a squad's specification and current state.
- * Validates data at system boundary.
- *
- * @param session - The parent session
- * @param squadId - ID of the squad to retrieve
- * @returns Squad spec and state, or null if not found
- * @throws ValidationError if data is corrupted
- *
- * @example
- * const squad = await getSquad(session, "squad-a1b2c3d4");
- * if (squad) {
- *   console.log(`Squad status: ${squad.state.status}`);
- * }
- */
 export async function getSquad(session, squadId) {
     const squadPath = `${session.sessionPath}/squads/${squadId}`;
     const rawSpec = await session.storage.read(`${squadPath}/spec.json`);
     const rawState = await session.storage.read(`${squadPath}/state.json`);
     if (!rawSpec || !rawState)
         return null;
-    // 경계에서 검증 - Parse, don't validate
     try {
         const spec = validateSquadSpec(rawSpec);
         const state = validateSquadState(rawState);
@@ -101,22 +54,6 @@ export async function getSquad(session, squadId) {
         throw new ValidationError(`Invalid squad data for ${squadId}`, { squadId, error: error instanceof Error ? error.message : String(error) });
     }
 }
-/**
- * Update a squad's state with partial changes.
- * Automatically updates the `updatedAt` timestamp.
- *
- * @param session - The parent session
- * @param squadId - ID of the squad to update
- * @param updates - Partial state updates to apply
- * @returns The new state after update
- * @throws {StorageError} If the squad doesn't exist
- *
- * @example
- * const newState = await updateSquadState(session, "squad-a1b2c3d4", {
- *   status: "active",
- *   progress: 50
- * });
- */
 export async function updateSquadState(session, squadId, updates) {
     const squad = await getSquad(session, squadId);
     if (!squad) {