claude-flow-novice 1.6.1 → 1.6.2

package/examples/session-pool-optimizer-example.ts

@@ -0,0 +1,311 @@
+/**
+ * Session Pool Optimizer - Usage Examples
+ *
+ * Demonstrates how to use the SessionPoolOptimizer for managing
+ * 50+ concurrent agent sessions with efficient resource management.
+ */
+
+import { SessionPoolOptimizer } from '../src/coordination/v2/sdk/session-pool-optimizer.js';
+import type { SessionRequest, PoolMetrics } from '../src/coordination/v2/sdk/session-pool-optimizer.js';
+
+/**
+ * Example 1: Basic Session Pool Setup
+ */
+async function basicPoolSetup() {
+  console.log('=== Example 1: Basic Session Pool Setup ===\n');
+
+  // Initialize pool with default configuration
+  const pool = new SessionPoolOptimizer({
+    maxPoolSize: 60,
+    minPoolSize: 10,
+    autoScaleThreshold: 80,
+  });
+
+  await pool.initialize();
+
+  // Acquire session for an agent
+  const session = await pool.acquireSession({
+    agentId: 'agent-1',
+    priority: 8,
+    metadata: { task: 'feature-development' },
+  });
+
+  console.log(`Session acquired: ${session.sessionId}`);
+  console.log(`Agent ID: ${session.agentId}`);
+  console.log(`Priority: ${session.metadata.priority}`);
+
+  // Release session
+  await pool.releaseSession(session.sessionId);
+  console.log('Session released back to pool\n');
+
+  await pool.shutdown();
+}
+
+/**
+ * Example 2: Handling 50+ Concurrent Agents
+ */
+async function handleConcurrentAgents() {
+  console.log('=== Example 2: Handling 50+ Concurrent Agents ===\n');
+
+  const pool = new SessionPoolOptimizer({
+    maxPoolSize: 70,
+    minPoolSize: 15,
+    throttleLimit: 10,
+  });
+
+  await pool.initialize();
+
+  // Simulate 55 concurrent agents
+  const agentRequests: SessionRequest[] = [];
+  for (let i = 0; i < 55; i++) {
+    agentRequests.push({
+      agentId: `concurrent-agent-${i}`,
+      priority: Math.floor(Math.random() * 10),
+      metadata: { index: i },
+    });
+  }
+
+  // Acquire sessions concurrently
+  console.log('Acquiring 55 sessions concurrently...');
+  const sessions = await Promise.all(
+    agentRequests.map((req) => pool.acquireSession(req))
+  );
+
+  const metrics = pool.getMetrics();
+  console.log(`\nPool Metrics:`);
+  console.log(`- Current pool size: ${metrics.currentPoolSize}`);
+  console.log(`- Active sessions: ${metrics.activeSessions}`);
+  console.log(`- Utilization: ${metrics.utilizationPercent.toFixed(1)}%`);
+  console.log(`- Auto-scale events: ${metrics.autoScaleEvents}`);
+
+  // Release all sessions
+  await Promise.all(sessions.map((s) => pool.releaseSession(s.sessionId)));
+  console.log('\nAll sessions released\n');
+
+  await pool.shutdown();
+}
+
+/**
+ * Example 3: Session Reuse and Efficiency
+ */
+async function sessionReuseExample() {
+  console.log('=== Example 3: Session Reuse and Efficiency ===\n');
+
+  const pool = new SessionPoolOptimizer({
+    maxPoolSize: 30,
+    minPoolSize: 5,
+    enableReuse: true,
+  });
+
+  await pool.initialize();
+
+  // Create and release sessions
+  const session1 = await pool.acquireSession({
+    agentId: 'agent-reuse-1',
+    priority: 5,
+  });
+  console.log(`Session 1 created: ${session1.sessionId}`);
+  await pool.releaseSession(session1.sessionId);
+
+  // Acquire new session (should reuse idle session)
+  const session2 = await pool.acquireSession({
+    agentId: 'agent-reuse-2',
+    priority: 6,
+  });
+
+  const metrics = pool.getMetrics();
+  console.log(`\nReuse Statistics:`);
+  console.log(`- Total sessions created: ${metrics.totalCreated}`);
+  console.log(`- Total reuses: ${metrics.totalReuses}`);
+  console.log(`- Idle sessions: ${metrics.idleSessions}`);
+
+  await pool.releaseSession(session2.sessionId);
+  await pool.shutdown();
+}
+
+/**
+ * Example 4: Health Checks and Auto-Recovery
+ */
+async function healthCheckExample() {
+  console.log('\n=== Example 4: Health Checks and Auto-Recovery ===\n');
+
+  const pool = new SessionPoolOptimizer({
+    maxPoolSize: 25,
+    minPoolSize: 5,
+    healthCheckIntervalMs: 5000, // 5 seconds
+    enableAutoRecovery: true,
+  });
+
+  await pool.initialize();
+
+  // Listen for health check events
+  pool.on('health:checked', (event) => {
+    console.log(`Health Check: ${event.healthyCount}/${event.totalChecked} healthy (${event.passRate.toFixed(1)}%)`);
+  });
+
+  // Create some sessions
+  await pool.acquireSession({ agentId: 'health-agent-1', priority: 5 });
+  await pool.acquireSession({ agentId: 'health-agent-2', priority: 6 });
+
+  console.log('Waiting for health checks...');
+  await new Promise((resolve) => setTimeout(resolve, 6000));
+
+  const metrics = pool.getMetrics();
+  console.log(`\nHealth Metrics:`);
+  console.log(`- Health check pass rate: ${metrics.healthCheckPassRate.toFixed(1)}%`);
+  console.log(`- Unhealthy sessions: ${metrics.unhealthySessions}`);
+
+  await pool.shutdown();
+}
+
+/**
+ * Example 5: Session Pinning for Critical Sessions
+ */
+async function sessionPinningExample() {
+  console.log('\n=== Example 5: Session Pinning for Critical Sessions ===\n');
+
+  const pool = new SessionPoolOptimizer({
+    maxPoolSize: 20,
+    minPoolSize: 5,
+  });
+
+  await pool.initialize();
+
+  // Acquire critical session
+  const criticalSession = await pool.acquireSession({
+    agentId: 'critical-agent',
+    priority: 10,
+    metadata: { critical: true },
+  });
+
+  // Pin session to prevent eviction
+  pool.pinSession(criticalSession.sessionId);
+  console.log(`Critical session pinned: ${criticalSession.sessionId}`);
+
+  const session = pool.getSession(criticalSession.sessionId);
+  console.log(`Is pinned: ${session?.metadata.isPinned}`);
+
+  // Later, unpin when no longer critical
+  pool.unpinSession(criticalSession.sessionId);
+  console.log('Session unpinned\n');
+
+  await pool.releaseSession(criticalSession.sessionId);
+  await pool.shutdown();
+}
+
+/**
+ * Example 6: Metrics Monitoring
+ */
+async function metricsMonitoringExample() {
+  console.log('=== Example 6: Metrics Monitoring ===\n');
+
+  const pool = new SessionPoolOptimizer({
+    maxPoolSize: 40,
+    minPoolSize: 10,
+  });
+
+  await pool.initialize();
+
+  // Create workload
+  for (let i = 0; i < 15; i++) {
+    await pool.acquireSession({
+      agentId: `metrics-agent-${i}`,
+      priority: Math.floor(Math.random() * 10),
+    });
+  }
+
+  const metrics = pool.getMetrics();
+
+  console.log('Pool Metrics Dashboard:');
+  console.log('========================');
+  console.log(`Pool Size: ${metrics.currentPoolSize} (max: 40)`);
+  console.log(`Active Sessions: ${metrics.activeSessions}`);
+  console.log(`Idle Sessions: ${metrics.idleSessions}`);
+  console.log(`Utilization: ${metrics.utilizationPercent.toFixed(1)}%`);
+  console.log(`\nLifetime Statistics:`);
+  console.log(`Total Created: ${metrics.totalCreated}`);
+  console.log(`Total Evicted: ${metrics.totalEvicted}`);
+  console.log(`Total Reuses: ${metrics.totalReuses}`);
+  console.log(`Avg Lifetime: ${(metrics.averageLifetimeMs / 1000).toFixed(2)}s`);
+  console.log(`\nPerformance:`);
+  console.log(`Request Rate: ${metrics.requestRate} req/s`);
+  console.log(`Health Pass Rate: ${metrics.healthCheckPassRate.toFixed(1)}%`);
+  console.log(`Auto-scale Events: ${metrics.autoScaleEvents}\n`);
+
+  await pool.shutdown();
+}
+
+/**
+ * Example 7: Event-Driven Architecture
+ */
+async function eventDrivenExample() {
+  console.log('=== Example 7: Event-Driven Architecture ===\n');
+
+  const pool = new SessionPoolOptimizer({
+    maxPoolSize: 30,
+    minPoolSize: 8,
+  });
+
+  // Set up event listeners
+  pool.on('session:created', (event) => {
+    console.log(`✓ Session created: ${event.sessionId} for ${event.agentId}`);
+  });
+
+  pool.on('session:reused', (event) => {
+    console.log(`♻️  Session reused: ${event.sessionId} for ${event.agentId}`);
+  });
+
+  pool.on('session:released', (event) => {
+    console.log(`↓ Session released: ${event.sessionId}`);
+  });
+
+  pool.on('pool:autoscaled', (event) => {
+    console.log(`📈 Pool auto-scaled: ${event.previousSize} → ${event.newSize}`);
+  });
+
+  await pool.initialize();
+
+  // Trigger events
+  const session1 = await pool.acquireSession({ agentId: 'event-agent-1', priority: 7 });
+  await pool.releaseSession(session1.sessionId);
+
+  const session2 = await pool.acquireSession({ agentId: 'event-agent-2', priority: 8 });
+  await pool.releaseSession(session2.sessionId);
+
+  console.log('');
+  await pool.shutdown();
+}
+
+/**
+ * Run all examples
+ */
+async function runAllExamples() {
+  try {
+    await basicPoolSetup();
+    await handleConcurrentAgents();
+    await sessionReuseExample();
+    await healthCheckExample();
+    await sessionPinningExample();
+    await metricsMonitoringExample();
+    await eventDrivenExample();
+
+    console.log('✅ All examples completed successfully!');
+  } catch (error) {
+    console.error('❌ Example failed:', error);
+  }
+}
+
+// Run examples if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runAllExamples();
+}
+
+export {
+  basicPoolSetup,
+  handleConcurrentAgents,
+  sessionReuseExample,
+  healthCheckExample,
+  sessionPinningExample,
+  metricsMonitoringExample,
+  eventDrivenExample,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow-novice",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "Standalone Claude Flow for beginners - AI agent orchestration made easy with enhanced TDD testing pipeline. Enhanced init command creates complete agent system, MCP configuration with 30 essential tools, and automated hooks with single-file testing, real-time coverage analysis, and advanced validation. Fully standalone with zero external dependencies, complete project setup in one command.",
   "mcpName": "io.github.ruvnet/claude-flow",
   "main": ".claude-flow-novice/dist/index.js",
@@ -205,6 +205,7 @@
     "src/npx/",
     "src/language/",
     "src/hooks/",
+    "src/observability/",
     "examples/",
     "wiki/",
     "CLAUDE.md",
@@ -229,6 +230,9 @@
     "./slash-commands/parse-epic": "./.claude-flow-novice/dist/src/slash-commands/parse-epic.js",
     "./slash-commands/custom-routing-activate": "./.claude-flow-novice/dist/src/slash-commands/custom-routing-activate.js",
     "./slash-commands/custom-routing-deactivate": "./.claude-flow-novice/dist/src/slash-commands/custom-routing-deactivate.js",
+    "./slash-commands/metrics-summary": "./.claude-flow-novice/dist/src/slash-commands/metrics-summary.js",
+    "./observability/metrics-counter": "./.claude-flow-novice/dist/src/observability/metrics-counter.js",
+    "./observability/metrics-storage": "./.claude-flow-novice/dist/src/observability/metrics-storage.js",
     "./providers": "./.claude-flow-novice/dist/src/providers/index.js",
     "./providers/zai": "./.claude-flow-novice/dist/src/providers/zai-provider.js",
     "./providers/tiered-router": "./.claude-flow-novice/dist/src/providers/tiered-router.js",
@@ -241,11 +245,15 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.1",
     "@modelcontextprotocol/sdk": "^1.18.2",
+    "@types/bcrypt": "^6.0.0",
+    "@types/express-rate-limit": "^5.1.3",
     "@types/msgpack-lite": "^0.1.11",
     "@types/msgpack5": "^3.4.6",
+    "@types/winston": "^2.4.4",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "async-mutex": "^0.5.0",
+    "bcrypt": "^6.0.0",
     "better-sqlite3": "^12.4.1",
     "boxen": "^8.0.1",
     "chalk": "^4.1.2",
@@ -253,11 +261,14 @@
     "commander": "^13.1.0",
     "compression": "^1.7.4",
     "cors": "^2.8.5",
+    "express-rate-limit": "^8.1.0",
     "fs-extra": "^11.2.0",
     "glob": "^11.0.0",
-    "helmet": "^7.0.0",
+    "helmet": "^7.2.0",
     "inquirer": "^12.9.6",
     "isomorphic-dompurify": "^2.28.0",
+    "jsonwebtoken": "^9.0.2",
+    "limiter": "^3.0.0",
     "lru-cache": "^11.2.2",
     "msgpack-lite": "^0.1.26",
     "msgpack5": "^6.0.2",
@@ -266,6 +277,7 @@
     "socket.io": "^4.8.1",
     "table": "^6.8.0",
     "uuid": "^13.0.0",
+    "winston": "^3.18.3",
     "ws": "^8.14.0",
     "yaml": "^2.8.1",
     "zod": "^3.25.76"
@@ -281,7 +293,7 @@
     "@swc/core": "^1.13.19",
     "@types/blessed": "^0.1.25",
     "@types/commander": "^2.12.0",
-    "@types/cors": "^2.8.17",
+    "@types/cors": "^2.8.19",
     "@types/express": "^4.17.21",
     "@types/figlet": "^1.7.0",
     "@types/fs-extra": "^11.0.4",

package/scripts/check-routing-stats.cjs

@@ -0,0 +1,122 @@
+/**
+ * Check Provider Routing Statistics
+ *
+ * Queries telemetry to show routing breakdown from recent swarm execution
+ */
+
+const { TelemetrySystem, getGlobalTelemetry } = require('../.claude-flow-novice/dist/src/observability/telemetry.js');
+
+async function checkRoutingStats() {
+  console.log('📊 Provider Routing Statistics\n');
+  console.log('=' .repeat(60));
+
+  try {
+    // Get global telemetry instance
+    const telemetry = getGlobalTelemetry();
+
+    // Query provider request metrics
+    const providerMetrics = telemetry.getMetrics('provider.request', 300000); // Last 5 minutes
+
+    if (providerMetrics.length === 0) {
+      console.log('\n⚠️  No routing metrics found in the last 5 minutes.');
+      console.log('   This may be because:');
+      console.log('   - Telemetry was initialized in a different process');
+      console.log('   - No tiered routing requests were made');
+      console.log('   - Metrics have expired (5 min window)');
+      console.log('\nTo test routing, run: node scripts/test-routing-telemetry.cjs\n');
+      return;
+    }
+
+    console.log(`\n✅ Found ${providerMetrics.length} routing metrics\n`);
+
+    // Aggregate by provider
+    const providerBreakdown = {};
+    const tierBreakdown = {};
+    const agentTypeBreakdown = {};
+    const sourceBreakdown = {};
+
+    providerMetrics.forEach(metric => {
+      const provider = metric.tags.provider || 'unknown';
+      const tier = metric.tags.tier || 'unknown';
+      const agentType = metric.tags.agentType || 'unknown';
+      const source = metric.tags.source || 'unknown';
+
+      providerBreakdown[provider] = (providerBreakdown[provider] || 0) + metric.value;
+      tierBreakdown[tier] = (tierBreakdown[tier] || 0) + metric.value;
+      agentTypeBreakdown[agentType] = (agentTypeBreakdown[agentType] || 0) + metric.value;
+      sourceBreakdown[source] = (sourceBreakdown[source] || 0) + metric.value;
+    });
+
+    // Display results
+    console.log('📍 BY PROVIDER:');
+    console.log('-'.repeat(60));
+    Object.entries(providerBreakdown)
+      .sort((a, b) => b[1] - a[1])
+      .forEach(([provider, count]) => {
+        const percentage = ((count / providerMetrics.length) * 100).toFixed(1);
+        const providerName = provider === 'custom' ? 'Z.ai (free tier)' :
+                           provider === 'anthropic' ? 'Anthropic API' : provider;
+        console.log(`  ${providerName.padEnd(30)} ${count.toString().padStart(3)} requests (${percentage}%)`);
+      });
+
+    console.log('\n🎯 BY TIER:');
+    console.log('-'.repeat(60));
+    Object.entries(tierBreakdown)
+      .sort((a, b) => b[1] - a[1])
+      .forEach(([tier, count]) => {
+        const percentage = ((count / providerMetrics.length) * 100).toFixed(1);
+        console.log(`  ${tier.padEnd(30)} ${count.toString().padStart(3)} requests (${percentage}%)`);
+      });
+
+    console.log('\n🤖 BY AGENT TYPE:');
+    console.log('-'.repeat(60));
+    Object.entries(agentTypeBreakdown)
+      .sort((a, b) => b[1] - a[1])
+      .forEach(([agentType, count]) => {
+        const percentage = ((count / providerMetrics.length) * 100).toFixed(1);
+        console.log(`  ${agentType.padEnd(30)} ${count.toString().padStart(3)} requests (${percentage}%)`);
+      });
+
+    console.log('\n🔀 BY ROUTING SOURCE:');
+    console.log('-'.repeat(60));
+    Object.entries(sourceBreakdown)
+      .sort((a, b) => b[1] - a[1])
+      .forEach(([source, count]) => {
+        const percentage = ((count / providerMetrics.length) * 100).toFixed(1);
+        console.log(`  ${source.padEnd(30)} ${count.toString().padStart(3)} requests (${percentage}%)`);
+      });
+
+    // Check for subscription metrics
+    const subMetrics = telemetry.getMetrics('subscription.usage', 300000);
+    if (subMetrics.length > 0) {
+      const latestSub = subMetrics[subMetrics.length - 1];
+      console.log('\n📈 SUBSCRIPTION USAGE:');
+      console.log('-'.repeat(60));
+      console.log(`  Used:      ${latestSub.value}/${latestSub.tags.limit}`);
+      console.log(`  Remaining: ${latestSub.tags.remaining}`);
+      console.log(`  Status:    ${latestSub.value >= parseInt(latestSub.tags.limit) ? '⚠️  LIMIT REACHED' : '✅ Available'}`);
+    }
+
+    // Throughput analysis
+    const throughput = telemetry.getThroughputMetrics('provider.request', 300000);
+    console.log('\n⚡ THROUGHPUT ANALYSIS:');
+    console.log('-'.repeat(60));
+    console.log(`  Total requests:    ${throughput.totalRequests}`);
+    console.log(`  Requests/sec:      ${throughput.requestsPerSecond.toFixed(2)}`);
+    console.log(`  Time window:       Last 5 minutes`);
+
+    console.log('\n' + '='.repeat(60));
+    console.log('✅ Routing statistics retrieved successfully\n');
+
+  } catch (error) {
+    console.error('❌ Error retrieving routing statistics:', error.message);
+    console.error('\nThis may happen if telemetry is not initialized.');
+    console.error('Try running a routing test first: node scripts/test-routing-telemetry.cjs\n');
+  }
+}
+
+// Run stats check
+checkRoutingStats().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});