@claudetools/tools 0.8.4 → 0.8.6

package/dist/helpers/tasks.js

@@ -3,6 +3,7 @@
 // =============================================================================
 import { apiRequest } from './api-client.js';
 import { matchTaskToWorker, buildWorkerPrompt } from './workers.js';
+import { isCircuitOpen } from './circuit-breaker.js';
 export function parseJsonArray(value) {
     if (!value)
         return [];
@@ -51,11 +52,12 @@ export async function getTask(userId, projectId, taskId, full = false) {
     const endpoint = full ? 'full' : '';
     return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}${endpoint ? `/${endpoint}` : ''}`);
 }
-export async function claimTask(userId, projectId, taskId, agentId, lockDurationMinutes = 30) {
-    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/claim`, 'POST', {
-        agent_id: agentId,
-        lock_duration_minutes: lockDurationMinutes,
-    });
+export async function claimTask(userId, projectId, taskId, agentId, lockDurationMinutes) {
+    const body = { agent_id: agentId };
+    if (lockDurationMinutes !== undefined) {
+        body.lock_duration_minutes = lockDurationMinutes;
+    }
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/claim`, 'POST', body);
 }
 export async function releaseTask(userId, projectId, taskId, agentId, newStatus, workLog) {
     return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/release`, 'POST', {
@@ -90,11 +92,29 @@ export async function heartbeatTask(userId, projectId, taskId, agentId, extendMi
 // -----------------------------------------------------------------------------
 // Orchestration Functions
 // -----------------------------------------------------------------------------
-// Configuration: Default maximum parallel tasks
-export const DEFAULT_MAX_PARALLEL = 5;
+// Effort weights for capacity planning
+export const EFFORT_WEIGHTS = {
+    xs: 1,
+    s: 2,
+    m: 4,
+    l: 8,
+    xl: 16,
+};
+// Default lock duration by effort size (in minutes)
+// Used when no explicit lockDurationMinutes is provided to claimTask
+export const LOCK_DURATION_BY_EFFORT = {
+    xs: 15, // Extra small: 15 minutes
+    s: 30, // Small: 30 minutes (default)
+    m: 60, // Medium: 1 hour
+    l: 120, // Large: 2 hours
+    xl: 240, // Extra large: 4 hours
+};
+// Configuration: Default capacity budget in effort units
+// 20 units allows: 20 xs tasks OR 1 xl + 1 m task OR 5 m tasks, etc.
+export const DEFAULT_CAPACITY_BUDGET = 20;
 /**
- * Get count of currently active tasks
- * Returns both in_progress and claimed (locked) task counts
+ * Get effort-weighted load of currently active tasks
+ * Returns both in_progress and claimed (locked) task counts, plus effort-weighted load
  */
 export async function getActiveTaskCount(userId, projectId, epicId) {
     // Get all in_progress tasks
@@ -105,10 +125,15 @@ export async function getActiveTaskCount(userId, projectId, epicId) {
     });
     let inProgressCount = 0;
     let claimedCount = 0;
+    let effortLoad = 0;
     if (inProgressResult.success && inProgressResult.data.length > 0) {
         const now = new Date();
         for (const task of inProgressResult.data) {
             inProgressCount++;
+            // Calculate effort weight (default to 'm' = 4 units if not specified)
+            const effort = task.estimated_effort || 'm';
+            const weight = EFFORT_WEIGHTS[effort] || EFFORT_WEIGHTS.m;
+            effortLoad += weight;
             // Check if task is also claimed (has valid lock)
             if (task.assigned_to && task.lock_expires_at) {
                 const lockExpires = new Date(task.lock_expires_at);
@@ -122,6 +147,7 @@ export async function getActiveTaskCount(userId, projectId, epicId) {
         inProgress: inProgressCount,
         claimed: claimedCount,
         total: inProgressCount,
+        effortLoad,
     };
 }
 /**
@@ -130,13 +156,13 @@ export async function getActiveTaskCount(userId, projectId, epicId) {
  * - Excludes already claimed tasks
  * - Resolves dependencies (only returns unblocked tasks)
  * - Matches each to appropriate expert worker
- * - Respects max parallel limit by considering currently active tasks
+ * - Respects effort-weighted capacity budget
  */
-export async function getDispatchableTasks(userId, projectId, epicId, maxParallel = DEFAULT_MAX_PARALLEL) {
-    // Get current active task count
+export async function getDispatchableTasks(userId, projectId, epicId, capacityBudget = DEFAULT_CAPACITY_BUDGET) {
+    // Get current active task effort load
     const activeCount = await getActiveTaskCount(userId, projectId, epicId);
-    // Calculate remaining capacity
-    const remainingCapacity = maxParallel - activeCount.total;
+    // Calculate remaining effort capacity
+    let remainingCapacity = capacityBudget - activeCount.effortLoad;
     if (remainingCapacity <= 0) {
         // No capacity available, return empty array
         return [];
@@ -178,6 +204,13 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
                 continue; // Still blocked
             }
         }
+        // Calculate task effort weight
+        const effort = task.estimated_effort || 'm';
+        const taskEffort = EFFORT_WEIGHTS[effort] || EFFORT_WEIGHTS.m;
+        // Check if this task fits within remaining capacity
+        if (taskEffort > remainingCapacity) {
+            continue; // Task too large for remaining capacity
+        }
         // Match to expert worker
         const worker = matchTaskToWorker({
             title: task.title,
@@ -185,6 +218,11 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
             domain: task.domain || undefined,
             tags: parseJsonArray(task.tags),
         });
+        // Circuit breaker check: skip if worker circuit is open
+        if (isCircuitOpen(worker.id)) {
+            console.warn(`[Circuit Breaker] Skipping task ${task.id} - circuit OPEN for worker type: ${worker.id}`);
+            continue; // Skip this task
+        }
         // Get task context
         const fullTask = await getTask(userId, projectId, task.id, true);
         const taskData = fullTask.data;
@@ -195,13 +233,48 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
             parentContext: taskData.parent,
             dependencies: [],
         });
-        // Only dispatch tasks that fit within remaining capacity
-        if (dispatchable.length >= remainingCapacity) {
+        // Reduce remaining capacity by the effort of this task
+        remainingCapacity -= taskEffort;
+        // Stop if no capacity remains
+        if (remainingCapacity <= 0) {
             break;
         }
     }
+    // Sort by priority: critical → high → medium → low
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    dispatchable.sort((a, b) => (priorityOrder[a.task.priority] ?? 2) - (priorityOrder[b.task.priority] ?? 2));
     return dispatchable;
 }
+/**
+ * Check if task lock is about to expire and return warning
+ */
+export function getLockExpiryWarning(lockExpiresAt) {
+    if (!lockExpiresAt) {
+        return { warning: false, minutes_remaining: 0 };
+    }
+    const now = new Date();
+    const expiryTime = new Date(lockExpiresAt);
+    const secondsRemaining = (expiryTime.getTime() - now.getTime()) / 1000;
+    const minutesRemaining = Math.floor(secondsRemaining / 60);
+    // Expired (lock time has passed)
+    if (secondsRemaining <= 0) {
+        return {
+            warning: true,
+            minutes_remaining: 0,
+            message: '🚨 Lock has EXPIRED. Task may be claimed by another agent.',
+        };
+    }
+    // Warn if lock expires within 5 minutes (but not yet expired)
+    if (minutesRemaining <= 5 && minutesRemaining >= 1) {
+        return {
+            warning: true,
+            minutes_remaining: minutesRemaining,
+            message: `⚠️  Lock expires in ${minutesRemaining} minute${minutesRemaining !== 1 ? 's' : ''}. Call task_heartbeat to extend.`,
+        };
+    }
+    // Less than 1 minute but not expired - no warning (edge case)
+    return { warning: false, minutes_remaining: minutesRemaining };
+}
 /**
  * Get full execution context for a worker agent
  */
@@ -251,6 +324,8 @@ export async function getExecutionContext(userId, projectId, taskId) {
             status: s.status,
         })),
     });
+    // Check for lock expiry warning
+    const lockWarning = getLockExpiryWarning(task.lock_expires_at);
     return {
         task,
         worker,
@@ -258,6 +333,7 @@ export async function getExecutionContext(userId, projectId, taskId) {
         context: taskData.context,
         parentTask: taskData.parent,
         siblingTasks,
+        lockWarning,
     };
 }
 /**
@@ -303,6 +379,81 @@ export async function resolveTaskDependencies(userId, projectId, completedTaskId
     }
     return newlyUnblocked;
 }
+/**
+ * Aggregate work_log context from all tasks in an epic
+ * Used by orchestrator to synthesize final results
+ */
+export async function getEpicAggregate(userId, projectId, epicId, includePending = false) {
+    // Get the epic
+    const epicResult = await getTask(userId, projectId, epicId);
+    if (!epicResult.success) {
+        throw new Error(`Epic not found: ${epicId}`);
+    }
+    const epic = epicResult.data;
+    // Verify it's an epic
+    if (epic.type !== 'epic') {
+        throw new Error(`Task ${epicId} is not an epic (type: ${epic.type})`);
+    }
+    // Get all child tasks
+    const tasksResult = await listTasks(userId, projectId, {
+        parent_id: epicId,
+        limit: 100,
+    });
+    if (!tasksResult.success) {
+        return {
+            epic: {
+                id: epic.id,
+                title: epic.title,
+                description: epic.description,
+                status: epic.status,
+            },
+            tasks: [],
+            summary_stats: {
+                total: 0,
+                completed: 0,
+                in_progress: 0,
+                pending: 0,
+            },
+        };
+    }
+    const allTasks = tasksResult.data;
+    // Get work_log context for each task
+    const tasksWithLogs = await Promise.all(allTasks.map(async (task) => {
+        // Get full task data to access context
+        const fullTaskResult = await getTask(userId, projectId, task.id, true);
+        const fullTaskData = fullTaskResult.data;
+        // Find work_log context
+        const workLogContext = fullTaskData.context?.find(ctx => ctx.context_type === 'work_log');
+        return {
+            id: task.id,
+            title: task.title,
+            status: task.status,
+            work_log: workLogContext?.content || null,
+            completed_at: task.completed_at,
+        };
+    }));
+    // Filter based on includePending
+    const filteredTasks = includePending
+        ? tasksWithLogs
+        : tasksWithLogs.filter(t => t.status === 'done' || t.status === 'in_progress');
+    // Calculate stats
+    const stats = {
+        total: allTasks.length,
+        completed: allTasks.filter(t => t.status === 'done').length,
+        in_progress: allTasks.filter(t => t.status === 'in_progress').length,
+        pending: allTasks.filter(t => t.status === 'ready' || t.status === 'backlog').length,
+    };
+    return {
+        epic: {
+            id: epic.id,
+            title: epic.title,
+            description: epic.description,
+            status: epic.status,
+        },
+        tasks: filteredTasks,
+        summary_stats: stats,
+    };
+}
 /**
  * Get epic status with progress tracking
  * Auto-completes epic if all child tasks are done
@@ -368,3 +519,97 @@ export async function getEpicStatus(userId, projectId, epicId) {
         autoCompleted,
     };
 }
+export async function handoffTask(userId, projectId, taskId, agentId, newWorkerType, reason) {
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/handoff`, 'POST', {
+        agent_id: agentId,
+        new_worker_type: newWorkerType,
+        reason,
+    });
+}
+/**
+ * Revise an existing epic by adding/removing/updating tasks
+ * Enables iterative planning without recreating the entire epic
+ */
+export async function reviseEpic(userId, projectId, epicId, changes) {
+    // Verify epic exists and is not done
+    const epicResult = await getTask(userId, projectId, epicId);
+    if (!epicResult.success) {
+        throw new Error(`Epic not found: ${epicId}`);
+    }
+    const epic = epicResult.data;
+    if (epic.type !== 'epic') {
+        throw new Error(`Task ${epicId} is not an epic (type: ${epic.type})`);
+    }
+    if (epic.status === 'done') {
+        throw new Error(`Cannot revise completed epic: ${epicId}`);
+    }
+    const added = [];
+    const removed = [];
+    const updated = [];
+    // Add new tasks
+    if (changes.add_tasks && changes.add_tasks.length > 0) {
+        for (const taskDef of changes.add_tasks) {
+            const taskResult = await createTask(userId, projectId, {
+                type: 'task',
+                title: taskDef.title,
+                description: taskDef.description,
+                parent_id: epicId,
+                priority: epic.priority,
+                estimated_effort: taskDef.effort,
+                blocked_by: taskDef.blocked_by,
+                domain: taskDef.domain,
+            });
+            added.push(taskResult.data);
+        }
+    }
+    // Remove tasks (set to cancelled status)
+    if (changes.remove_task_ids && changes.remove_task_ids.length > 0) {
+        for (const taskId of changes.remove_task_ids) {
+            try {
+                await updateTaskStatus(userId, projectId, taskId, 'cancelled', 'system:epic-revision');
+                removed.push(taskId);
+            }
+            catch (error) {
+                // Log but continue - task may not exist
+                console.warn(`Failed to cancel task ${taskId}:`, error);
+            }
+        }
+    }
+    // Update existing tasks
+    // Note: The API doesn't support PATCH for tasks, so we can only update status
+    // For title/description/effort updates, we'll need to add context explaining the change
+    if (changes.update_tasks && changes.update_tasks.length > 0) {
+        for (const update of changes.update_tasks) {
+            try {
+                const taskResult = await getTask(userId, projectId, update.task_id);
+                if (!taskResult.success)
+                    continue;
+                const task = taskResult.data;
+                // Add context about the updates since we can't modify fields directly
+                const updates = [];
+                if (update.title && update.title !== task.title) {
+                    updates.push(`Title updated: "${task.title}" → "${update.title}"`);
+                }
+                if (update.description && update.description !== task.description) {
+                    updates.push(`Description updated: "${update.description}"`);
+                }
+                if (update.effort && update.effort !== task.estimated_effort) {
+                    updates.push(`Effort updated: ${task.estimated_effort || 'unset'} → ${update.effort}`);
+                }
+                if (updates.length > 0) {
+                    await addTaskContext(userId, projectId, update.task_id, 'decision', updates.join('\n'), 'task_plan_revise', 'epic-revision');
+                    updated.push(task);
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to update task ${update.task_id}:`, error);
+            }
+        }
+    }
+    return {
+        epic,
+        added,
+        removed,
+        updated,
+    };
+}

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 export type { ExpertWorker } from './helpers/workers.js';
 export type { Task, TaskContext, DispatchableTask } from './helpers/tasks.js';
 export type { DeduplicationTracker } from './context/index.js';
+export type { CircuitState } from './helpers/circuit-breaker.js';
+export type { TestResult, TestSuite, TestSuiteSummary, TestFunction, TestDefinition, } from './testing/index.js';
+export { runTest, runSuite, formatResults, formatResultsJson, assert, assertEqual, assertThrows, } from './testing/index.js';
 export { EXPERT_WORKERS, matchTaskToWorker } from './helpers/workers.js';
 export { parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask } from './helpers/tasks.js';
 export { injectContext } from './helpers/api-client.js';
 export { recordToolCall, getToolCallWarnings, getSessionStats, clearSessionState, recordContextReference, calculateEngagementScore, getEngagementStats } from './helpers/session-validation.js';
 export { createDeduplicationTracker, InMemoryDeduplicationTracker } from './context/index.js';
+export { recordWorkerFailure, isCircuitOpen, getCircuitStatus, resetCircuit, resetAllCircuits } from './helpers/circuit-breaker.js';
 export declare function startServer(): Promise<void>;

package/dist/index.js

@@ -11,12 +11,14 @@ import { registerToolHandlers } from './handlers/tool-handlers.js';
 // Resource and prompt handlers
 import { registerResourceHandlers } from './resources.js';
 import { registerPromptHandlers } from './prompts.js';
+export { runTest, runSuite, formatResults, formatResultsJson, assert, assertEqual, assertThrows, } from './testing/index.js';
 // Re-export functions that are used by handlers
 export { EXPERT_WORKERS, matchTaskToWorker } from './helpers/workers.js';
 export { parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask } from './helpers/tasks.js';
 export { injectContext } from './helpers/api-client.js';
 export { recordToolCall, getToolCallWarnings, getSessionStats, clearSessionState, recordContextReference, calculateEngagementScore, getEngagementStats } from './helpers/session-validation.js';
 export { createDeduplicationTracker, InMemoryDeduplicationTracker } from './context/index.js';
+export { recordWorkerFailure, isCircuitOpen, getCircuitStatus, resetCircuit, resetAllCircuits } from './helpers/circuit-breaker.js';
 // =============================================================================
 // Server Initialization
 // =============================================================================

package/dist/test-runner.d.ts

@@ -0,0 +1,33 @@
+export interface TestResult {
+    name: string;
+    status: 'pass' | 'fail' | 'error';
+    duration: number;
+    error?: string;
+    details?: any;
+}
+export interface TestSuiteResult {
+    totalTests: number;
+    passed: number;
+    failed: number;
+    errors: number;
+    duration: number;
+    tests: TestResult[];
+}
+export interface TestOptions {
+    verbose?: boolean;
+    json?: boolean;
+}
+/**
+ * Run all integration tests in the suite.
+ *
+ * This is the main entry point that imports and runs all test files:
+ * - Store-Retrieve-Verify test
+ * - Context Injection test
+ * - Task Lifecycle test
+ * - Cross-Project Isolation test
+ */
+export declare function runSuite(): Promise<TestSuiteResult>;
+/**
+ * Run tests from CLI with options.
+ */
+export declare function runTests(options?: TestOptions): Promise<void>;

package/dist/test-runner.js

@@ -0,0 +1,149 @@
+// =============================================================================
+// Integration Test Runner
+// =============================================================================
+// Runs the full integration test suite and outputs results
+// Supports --verbose and --json output formats
+// -----------------------------------------------------------------------------
+// Test Suite Runner
+// -----------------------------------------------------------------------------
+/**
+ * Run all integration tests in the suite.
+ *
+ * This is the main entry point that imports and runs all test files:
+ * - Store-Retrieve-Verify test
+ * - Context Injection test
+ * - Task Lifecycle test
+ * - Cross-Project Isolation test
+ */
+export async function runSuite() {
+    const startTime = Date.now();
+    const results = [];
+    // TODO: Import and run actual test files once they're implemented
+    // Example structure:
+    //
+    // import { runStoreRetrieveTest } from './__tests__/store-retrieve-verify.js';
+    // import { runContextInjectionTest } from './__tests__/context-injection.js';
+    // import { runTaskLifecycleTest } from './__tests__/task-lifecycle.js';
+    // import { runCrossProjectTest } from './__tests__/cross-project-isolation.js';
+    //
+    // const tests = [
+    //   { name: 'Store-Retrieve-Verify', fn: runStoreRetrieveTest },
+    //   { name: 'Context Injection', fn: runContextInjectionTest },
+    //   { name: 'Task Lifecycle', fn: runTaskLifecycleTest },
+    //   { name: 'Cross-Project Isolation', fn: runCrossProjectTest },
+    // ];
+    //
+    // for (const test of tests) {
+    //   const result = await runTest(test.name, test.fn);
+    //   results.push(result);
+    // }
+    // Placeholder: Add a simple test to demonstrate structure
+    results.push({
+        name: 'Placeholder Test',
+        status: 'pass',
+        duration: 0,
+        details: { message: 'Test harness ready - add actual tests' }
+    });
+    const duration = Date.now() - startTime;
+    const passed = results.filter(r => r.status === 'pass').length;
+    const failed = results.filter(r => r.status === 'fail').length;
+    const errors = results.filter(r => r.status === 'error').length;
+    return {
+        totalTests: results.length,
+        passed,
+        failed,
+        errors,
+        duration,
+        tests: results,
+    };
+}
+/**
+ * Run a single test and capture result.
+ */
+async function runTest(name, testFn) {
+    const startTime = Date.now();
+    try {
+        await testFn();
+        return {
+            name,
+            status: 'pass',
+            duration: Date.now() - startTime,
+        };
+    }
+    catch (error) {
+        const isAssertionError = error instanceof Error && error.message.includes('AssertionError');
+        return {
+            name,
+            status: isAssertionError ? 'fail' : 'error',
+            duration: Date.now() - startTime,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+// -----------------------------------------------------------------------------
+// Output Formatting
+// -----------------------------------------------------------------------------
+/**
+ * Format results as human-readable text.
+ */
+function formatHumanReadable(result, verbose) {
+    const lines = [];
+    lines.push('');
+    lines.push('Integration Test Suite Results');
+    lines.push('================================');
+    lines.push('');
+    lines.push(`Total Tests: ${result.totalTests}`);
+    lines.push(`Passed:      ${result.passed}`);
+    lines.push(`Failed:      ${result.failed}`);
+    lines.push(`Errors:      ${result.errors}`);
+    lines.push(`Duration:    ${result.duration}ms`);
+    lines.push('');
+    if (verbose || result.failed > 0 || result.errors > 0) {
+        lines.push('Test Details:');
+        lines.push('');
+        for (const test of result.tests) {
+            const statusIcon = test.status === 'pass' ? '✓' : '✗';
+            lines.push(`${statusIcon} ${test.name} (${test.duration}ms)`);
+            if (test.error) {
+                lines.push(`  Error: ${test.error}`);
+            }
+            if (verbose && test.details) {
+                lines.push(`  Details: ${JSON.stringify(test.details, null, 2)}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format results as JSON.
+ */
+function formatJSON(result) {
+    return JSON.stringify(result, null, 2);
+}
+// -----------------------------------------------------------------------------
+// CLI Entry Point
+// -----------------------------------------------------------------------------
+/**
+ * Run tests from CLI with options.
+ */
+export async function runTests(options = {}) {
+    const { verbose = false, json = false } = options;
+    try {
+        console.error('Running integration tests...\n');
+        const result = await runSuite();
+        if (json) {
+            console.log(formatJSON(result));
+        }
+        else {
+            console.log(formatHumanReadable(result, verbose));
+        }
+        // Exit with code 0 if all pass, 1 if any fail
+        const exitCode = result.failed + result.errors > 0 ? 1 : 0;
+        process.exit(exitCode);
+    }
+    catch (error) {
+        console.error('Fatal error running test suite:', error);
+        process.exit(1);
+    }
+}

package/dist/testing/example.d.ts

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

package/dist/testing/example.js

@@ -0,0 +1,63 @@
+// =============================================================================
+// Test Runner Example Usage
+// =============================================================================
+//
+// This file demonstrates how to use the test harness for integration testing.
+// Run with: tsx src/testing/example.ts
+//
+import { runSuite, formatResults, formatResultsJson, assert, assertEqual, assertThrows, } from './test-runner.js';
+// Example: Memory integration tests
+async function exampleUsage() {
+    const suite = await runSuite('Memory Integration Example', [
+        {
+            name: 'should pass basic assertion',
+            fn: async () => {
+                const value = 42;
+                assert(value === 42, 'Value should be 42');
+            },
+        },
+        {
+            name: 'should pass equality check',
+            fn: async () => {
+                const obj = { id: '123', name: 'Test' };
+                assertEqual(obj, { id: '123', name: 'Test' });
+            },
+        },
+        {
+            name: 'should catch expected errors',
+            fn: async () => {
+                await assertThrows(async () => {
+                    throw new Error('Invalid input');
+                }, 'Invalid input');
+            },
+        },
+        {
+            name: 'should fail on purpose',
+            fn: async () => {
+                // This test intentionally fails to demonstrate error handling
+                assert(false, 'This is a deliberate failure');
+            },
+        },
+        {
+            name: 'should handle async operations',
+            fn: async () => {
+                // Simulate async API call
+                await new Promise(resolve => setTimeout(resolve, 50));
+                const result = { success: true };
+                assert(result.success === true);
+            },
+        },
+    ]);
+    // Print human-readable results
+    console.log(formatResults(suite));
+    // Example: Save JSON results to file
+    console.log('\n--- JSON Output ---\n');
+    console.log(formatResultsJson(suite));
+    // Exit with appropriate code
+    process.exit(suite.summary.failed > 0 ? 1 : 0);
+}
+// Run example
+exampleUsage().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/testing/index.d.ts

@@ -0,0 +1 @@
+export { TestResult, TestSuite, TestSuiteSummary, TestFunction, TestDefinition, runTest, runSuite, formatResults, formatResultsJson, assert, assertEqual, assertThrows, } from './test-runner.js';

package/dist/testing/index.js

@@ -0,0 +1,13 @@
+// =============================================================================
+// Agent-Based Integration Testing
+// =============================================================================
+//
+// Re-exports for test runner and utilities
+//
+export { 
+// Core test runner functions
+runTest, runSuite, 
+// Formatting
+formatResults, formatResultsJson, 
+// Assertion helpers
+assert, assertEqual, assertThrows, } from './test-runner.js';