claude-flow-novice 1.6.1 → 1.6.2

package/examples/metrics-counter-demo.ts

@@ -0,0 +1,106 @@
+/**
+ * Metrics Counter Demo
+ *
+ * Demonstrates how to use the simple metrics counter API
+ */
+
+import {
+  incrementMetric,
+  recordGauge,
+  recordTiming,
+  measureExecution,
+  trackProviderRouting,
+  trackAgentSpawn,
+  trackAPICall,
+  trackError,
+  getMetricValue,
+  getMetricBreakdown,
+} from '../src/observability/metrics-counter.js';
+
+async function demo() {
+  console.log('📊 Metrics Counter Demo\n');
+
+  // ===== EXAMPLE 1: Simple Counter =====
+  console.log('1️⃣  Simple Counters:');
+  incrementMetric('user.login');
+  incrementMetric('user.login');
+  incrementMetric('user.login');
+  console.log('   ✅ Tracked 3 user logins');
+
+  // ===== EXAMPLE 2: Counter with Tags =====
+  console.log('\n2️⃣  Counters with Tags:');
+  incrementMetric('api.requests', 1, { endpoint: '/users', method: 'GET' });
+  incrementMetric('api.requests', 1, { endpoint: '/users', method: 'POST' });
+  incrementMetric('api.requests', 1, { endpoint: '/posts', method: 'GET' });
+  console.log('   ✅ Tracked API requests with endpoint/method tags');
+
+  // ===== EXAMPLE 3: Gauge Values =====
+  console.log('\n3️⃣  Gauge Values:');
+  recordGauge('queue.size', 42);
+  recordGauge('active.connections', 15, { region: 'us-east-1' });
+  recordGauge('cpu.usage', 67.5, { unit: 'percent' });
+  console.log('   ✅ Recorded queue size, connections, CPU usage');
+
+  // ===== EXAMPLE 4: Timing Metrics =====
+  console.log('\n4️⃣  Timing Metrics:');
+  recordTiming('database.query', 45, { query: 'SELECT' });
+  recordTiming('database.query', 120, { query: 'INSERT' });
+  console.log('   ✅ Recorded database query timings');
+
+  // ===== EXAMPLE 5: Automatic Timing with measureExecution =====
+  console.log('\n5️⃣  Automatic Execution Timing:');
+  const result = await measureExecution('task.process', async () => {
+    await new Promise(resolve => setTimeout(resolve, 100)); // Simulate work
+    return { processed: 100 };
+  }, { taskType: 'data-import' });
+  console.log(`   ✅ Measured execution: ${result.processed} items processed`);
+
+  // ===== EXAMPLE 6: Provider Routing Tracking =====
+  console.log('\n6️⃣  Provider Routing:');
+  trackProviderRouting('custom', 'Tier 2: Z.ai', 'coder', 'fallback');
+  trackProviderRouting('custom', 'Tier 2: Z.ai', 'researcher', 'fallback');
+  trackProviderRouting('anthropic', 'Tier 1: Subscription', 'coordinator', 'tier-config');
+  console.log('   ✅ Tracked 3 provider routing decisions');
+
+  // ===== EXAMPLE 7: Agent Lifecycle Tracking =====
+  console.log('\n7️⃣  Agent Lifecycle:');
+  trackAgentSpawn('coder', 'swarm-123', 'mesh');
+  trackAgentSpawn('tester', 'swarm-123', 'mesh');
+  console.log('   ✅ Tracked 2 agent spawns');
+
+  // ===== EXAMPLE 8: API Call Tracking =====
+  console.log('\n8️⃣  API Call Tracking:');
+  trackAPICall('/api/users', 'GET', 200, 45);
+  trackAPICall('/api/users', 'POST', 201, 120);
+  trackAPICall('/api/posts', 'GET', 200, 30);
+  console.log('   ✅ Tracked 3 API calls with status codes');
+
+  // ===== EXAMPLE 9: Error Tracking =====
+  console.log('\n9️⃣  Error Tracking:');
+  trackError('ValidationError', 'user-service', 'low');
+  trackError('DatabaseConnectionError', 'database', 'critical');
+  console.log('   ✅ Tracked 2 errors with severity levels');
+
+  // ===== EXAMPLE 10: Query Metrics =====
+  console.log('\n🔟 Query Metrics:');
+  const loginCount = getMetricValue('user.login');
+  console.log(`   Login count: ${loginCount}`);
+
+  const apiBreakdown = getMetricBreakdown('api.requests', 'endpoint');
+  console.log('   API requests by endpoint:');
+  Object.entries(apiBreakdown).forEach(([endpoint, count]) => {
+    console.log(`     ${endpoint}: ${count} requests`);
+  });
+
+  const providerBreakdown = getMetricBreakdown('provider.request', 'provider');
+  console.log('   Provider routing breakdown:');
+  Object.entries(providerBreakdown).forEach(([provider, count]) => {
+    const name = provider === 'custom' ? 'Z.ai' : provider;
+    console.log(`     ${name}: ${count} requests`);
+  });
+
+  console.log('\n✅ Demo complete! All metrics tracked successfully.\n');
+}
+
+// Run demo
+demo().catch(console.error);

package/examples/persistent-metrics-demo.ts

@@ -0,0 +1,83 @@
+/**
+ * Persistent Metrics Demo
+ *
+ * Demonstrates:
+ * 1. Metrics persist across restarts (stored in SQLite)
+ * 2. Query historical metrics
+ * 3. Aggregate metrics from multiple runs
+ */
+
+import { incrementMetric, trackProviderRouting } from '../src/observability/metrics-counter.js';
+import { getGlobalMetricsStorage } from '../src/observability/metrics-storage.js';
+
+async function demo() {
+  console.log('📊 Persistent Metrics Demo\n');
+  console.log('=' .repeat(60));
+
+  const storage = getGlobalMetricsStorage();
+
+  // Show database stats FIRST (to see if we have previous data)
+  const stats = storage.getStats();
+  console.log('\n📈 Database Stats (BEFORE adding new metrics):');
+  console.log(`  Total metrics stored: ${stats.totalMetrics}`);
+  console.log(`  Unique metric names: ${stats.uniqueNames}`);
+  console.log(`  Oldest metric: ${stats.oldestMetric || 'N/A'}`);
+  console.log(`  Newest metric: ${stats.newestMetric || 'N/A'}`);
+  console.log(`  Database size: ${stats.dbSizeMB} MB`);
+
+  if (stats.totalMetrics > 0) {
+    console.log('\n✅ Found previous metrics! They persisted across restarts.');
+  } else {
+    console.log('\n🆕 No previous metrics found. This is a fresh database.');
+  }
+
+  // Add new metrics in THIS run
+  console.log('\n➕ Adding new metrics in THIS run...');
+
+  incrementMetric('demo.run.count');
+  incrementMetric('user.actions', 1, { action: 'click', page: 'home' });
+  incrementMetric('user.actions', 1, { action: 'submit', page: 'form' });
+
+  trackProviderRouting('custom', 'Tier 2: Z.ai', 'coder', 'fallback');
+  trackProviderRouting('anthropic', 'Tier 1: Subscription', 'coordinator', 'tier-config');
+
+  console.log('  ✅ Added 5 metrics');
+
+  // Query metrics from ALL time (including previous runs)
+  console.log('\n🔍 Querying ALL historical metrics...');
+
+  const totalRuns = storage.getCounterTotal('demo.run.count');
+  console.log(`\n  Total demo runs (across ALL sessions): ${totalRuns}`);
+
+  const userActions = storage.getSummary('user.actions');
+  if (userActions) {
+    console.log(`\n  User actions summary:`);
+    console.log(`    Total actions: ${userActions.count}`);
+    console.log(`    By action type:`);
+    Object.entries(userActions.tags.action || {}).forEach(([action, count]) => {
+      console.log(`      ${action}: ${count}`);
+    });
+  }
+
+  const providerBreakdown = storage.getBreakdown('provider.request', 'provider');
+  console.log(`\n  Provider routing breakdown (ALL time):`);
+  Object.entries(providerBreakdown).forEach(([provider, count]) => {
+    const name = provider === 'custom' ? 'Z.ai' : provider;
+    console.log(`    ${name}: ${count} requests`);
+  });
+
+  // Show final stats
+  const finalStats = storage.getStats();
+  console.log('\n📊 Database Stats (AFTER adding new metrics):');
+  console.log(`  Total metrics stored: ${finalStats.totalMetrics}`);
+  console.log(`  Database size: ${finalStats.dbSizeMB} MB`);
+
+  console.log('\n' + '='.repeat(60));
+  console.log('✅ Demo complete!\n');
+  console.log('💡 TIP: Run this script multiple times to see metrics accumulate:');
+  console.log('   npx tsx examples/persistent-metrics-demo.ts\n');
+  console.log('📂 Database location: .claude-flow/metrics.db\n');
+}
+
+// Run demo
+demo().catch(console.error);

package/examples/phase-5-multi-level-control.ts

@@ -0,0 +1,282 @@
+/**
+ * Phase 5 - Sprint 5.2: Multi-Level Agent Control Example
+ *
+ * Demonstrates pause/inject/resume from Level 0 to any child level
+ *
+ * @module examples/phase-5-multi-level-control
+ */
+
+import { QueryController } from '../src/coordination/v2/sdk/query-controller.js';
+import { HierarchicalCoordinator } from '../src/agents/hierarchical-coordinator.js';
+import {
+  MultiLevelController,
+  InjectedCommandType,
+  createMultiLevelControllerWithHierarchy,
+} from '../src/coordination/v2/sdk/multi-level-control.js';
+
+/**
+ * Example: Multi-Level Agent Control
+ *
+ * Scenario:
+ * - Level 0: Supervisor (top-level coordinator)
+ * - Level 1: Team Leads (2 agents)
+ * - Level 2: Workers (3 agents under Team Lead A)
+ *
+ * Demonstrates:
+ * - Level 0 pauses any agent at any level
+ * - Level 0 injects commands to modify agent state/tasks
+ * - Level 0 resumes agents with commands applied
+ * - <100ms latency for all control operations
+ */
+async function multiLevelControlExample() {
+  console.log('=== Phase 5 - Sprint 5.2: Multi-Level Agent Control Example ===\n');
+
+  // Step 1: Initialize QueryController (Phase 0)
+  console.log('Step 1: Initialize QueryController for pause/resume...');
+  const queryController = new QueryController({
+    maxConcurrentAgents: 20,
+    defaultTokenBudget: 10000,
+    enableDynamicAllocation: true,
+  });
+  await queryController.initialize();
+  console.log('✓ QueryController initialized\n');
+
+  // Step 2: Initialize HierarchicalCoordinator (Phase 5)
+  console.log('Step 2: Initialize HierarchicalCoordinator for hierarchy management...');
+  const hierarchicalCoordinator = new HierarchicalCoordinator({
+    maxDepth: 10,
+    maxChildrenPerNode: 10,
+    enableDependencyTracking: true,
+  });
+  await hierarchicalCoordinator.initialize();
+  console.log('✓ HierarchicalCoordinator initialized\n');
+
+  // Step 3: Create Multi-Level Controller (Sprint 5.2)
+  console.log('Step 3: Create MultiLevelController integration layer...');
+  const multiLevelController = createMultiLevelControllerWithHierarchy(
+    queryController,
+    hierarchicalCoordinator,
+    {
+      maxControlLatencyMs: 100, // <100ms target
+      enableCommandQueue: true,
+      maxQueuedCommands: 50,
+    }
+  );
+  console.log('✓ MultiLevelController created\n');
+
+  // Step 4: Build 3-Level Agent Hierarchy
+  console.log('Step 4: Build 3-level agent hierarchy...');
+
+  // Level 0: Supervisor
+  const supervisor = await queryController.spawnAgent({
+    agentId: 'supervisor',
+    type: 'coordinator',
+    priority: 10,
+    metadata: { role: 'Level 0 Supervisor' },
+  });
+  await hierarchicalCoordinator.registerAgent(
+    'supervisor',
+    {
+      name: 'Supervisor',
+      type: 'coordinator',
+      level: 0,
+      status: 'ready',
+      capabilities: ['coordination', 'hierarchy-control'],
+    },
+    undefined // No parent (root)
+  );
+
+  // Level 1: Team Leads
+  const teamLeadA = await queryController.spawnAgent({
+    agentId: 'team-lead-a',
+    type: 'coordinator',
+    priority: 8,
+    metadata: { role: 'Team Lead A' },
+  });
+  await hierarchicalCoordinator.registerAgent(
+    'team-lead-a',
+    {
+      name: 'Team Lead A',
+      type: 'coordinator',
+      level: 1,
+      status: 'ready',
+      capabilities: ['coordination', 'task-delegation'],
+    },
+    'supervisor' // Parent: supervisor
+  );
+
+  const teamLeadB = await queryController.spawnAgent({
+    agentId: 'team-lead-b',
+    type: 'coordinator',
+    priority: 8,
+    metadata: { role: 'Team Lead B' },
+  });
+  await hierarchicalCoordinator.registerAgent(
+    'team-lead-b',
+    {
+      name: 'Team Lead B',
+      type: 'coordinator',
+      level: 1,
+      status: 'ready',
+      capabilities: ['coordination', 'task-delegation'],
+    },
+    'supervisor'
+  );
+
+  // Level 2: Workers (under Team Lead A)
+  const workerA1 = await queryController.spawnAgent({
+    agentId: 'worker-a1',
+    type: 'worker',
+    priority: 5,
+    metadata: { role: 'Worker A1' },
+  });
+  await hierarchicalCoordinator.registerAgent(
+    'worker-a1',
+    {
+      name: 'Worker A1',
+      type: 'worker',
+      level: 2,
+      status: 'ready',
+      capabilities: ['code-generation', 'testing'],
+    },
+    'team-lead-a'
+  );
+
+  const workerA2 = await queryController.spawnAgent({
+    agentId: 'worker-a2',
+    type: 'worker',
+    priority: 5,
+    metadata: { role: 'Worker A2' },
+  });
+  await hierarchicalCoordinator.registerAgent(
+    'worker-a2',
+    {
+      name: 'Worker A2',
+      type: 'worker',
+      level: 2,
+      status: 'ready',
+      capabilities: ['documentation', 'review'],
+    },
+    'team-lead-a'
+  );
+
+  console.log('✓ Hierarchy built:');
+  console.log('  - Level 0: Supervisor');
+  console.log('  - Level 1: Team Lead A, Team Lead B');
+  console.log('  - Level 2: Worker A1, Worker A2\n');
+
+  // Step 5: Demonstrate Multi-Level Control Operations
+  console.log('Step 5: Multi-Level Control Operations\n');
+
+  // Operation 1: Level 0 pauses Level 2 agent
+  console.log('Operation 1: Supervisor (L0) pauses Worker A1 (L2)...');
+  const pauseResult = await multiLevelController.pauseChildAgent(
+    'supervisor',
+    'worker-a1',
+    'Supervisor directive: pause for configuration update'
+  );
+  console.log(`✓ Paused: ${pauseResult.success}`);
+  console.log(`  - Agent: ${pauseResult.agentId} (Level ${pauseResult.level})`);
+  console.log(`  - Latency: ${pauseResult.latencyMs.toFixed(2)}ms (<100ms target)\n`);
+
+  // Operation 2: Level 0 injects commands to paused agent
+  console.log('Operation 2: Supervisor (L0) injects commands to Worker A1 (L2)...');
+
+  const stateInjection = await multiLevelController.injectCommand(
+    'supervisor',
+    'worker-a1',
+    InjectedCommandType.STATE_UPDATE,
+    { state: 'working' },
+    false
+  );
+  console.log(`✓ Injected STATE_UPDATE: ${stateInjection.success} (${stateInjection.latencyMs.toFixed(2)}ms)`);
+
+  const taskInjection = await multiLevelController.injectCommand(
+    'supervisor',
+    'worker-a1',
+    InjectedCommandType.TASK_UPDATE,
+    {
+      task: 'Implement authentication module',
+      taskId: 'task-auth-001',
+      deadline: '2025-10-15',
+    },
+    false
+  );
+  console.log(`✓ Injected TASK_UPDATE: ${taskInjection.success} (${taskInjection.latencyMs.toFixed(2)}ms)`);
+
+  const priorityInjection = await multiLevelController.injectCommand(
+    'supervisor',
+    'worker-a1',
+    InjectedCommandType.PRIORITY_UPDATE,
+    { priority: 9 },
+    false
+  );
+  console.log(`✓ Injected PRIORITY_UPDATE: ${priorityInjection.success} (${priorityInjection.latencyMs.toFixed(2)}ms)`);
+
+  const queuedCount = multiLevelController.getQueuedCommandsCount('worker-a1');
+  console.log(`  - Queued commands: ${queuedCount}\n`);
+
+  // Operation 3: Level 0 resumes agent with commands applied
+  console.log('Operation 3: Supervisor (L0) resumes Worker A1 (L2)...');
+  const resumeResult = await multiLevelController.resumeChildAgent('supervisor', 'worker-a1');
+  console.log(`✓ Resumed: ${resumeResult.success}`);
+  console.log(`  - Commands applied: ${resumeResult.data?.appliedCommands}`);
+  console.log(`  - Latency: ${resumeResult.latencyMs.toFixed(2)}ms\n`);
+
+  // Verify commands were applied
+  const workerSession = await queryController.getAgentSession('worker-a1');
+  console.log('✓ Verification:');
+  console.log(`  - Worker A1 state: ${workerSession.state}`);
+  console.log(`  - Worker A1 priority: ${workerSession.priority}`);
+  console.log(`  - Injected commands: ${workerSession.metadata.injectedCommands?.length ?? 0}\n`);
+
+  // Operation 4: Cascade pause to all Team Lead A's children
+  console.log('Operation 4: Supervisor (L0) cascades pause to all Team Lead A children...');
+  const cascadeResults = await multiLevelController.cascadeControlOperation('team-lead-a', 'pause');
+  console.log(`✓ Cascade pause completed: ${cascadeResults.length} agents affected`);
+  for (const result of cascadeResults) {
+    console.log(
+      `  - ${result.agentId} (L${result.level}): ${result.success ? 'Paused' : 'Failed'} (${result.latencyMs.toFixed(2)}ms)`
+    );
+  }
+  console.log('');
+
+  // Operation 5: Cascade resume
+  console.log('Operation 5: Supervisor (L0) cascades resume to all Team Lead A children...');
+  const resumeCascade = await multiLevelController.cascadeControlOperation('team-lead-a', 'resume');
+  console.log(`✓ Cascade resume completed: ${resumeCascade.length} agents resumed\n`);
+
+  // Step 6: Show Final Metrics
+  console.log('Step 6: Control Operation Metrics');
+  const metrics = multiLevelController.getMetrics();
+  console.log(`  - Total pauses: ${metrics.totalPauses}`);
+  console.log(`  - Total injections: ${metrics.totalInjections}`);
+  console.log(`  - Total resumes: ${metrics.totalResumes}`);
+  console.log(`  - Average latency: ${metrics.averageControlLatencyMs.toFixed(2)}ms`);
+  console.log(`  - Max latency: ${metrics.maxControlLatencyMs.toFixed(2)}ms`);
+  console.log(`  - Within <100ms target: ${metrics.withinTarget ? 'YES ✓' : 'NO ✗'}\n`);
+
+  // Cleanup
+  console.log('Cleanup...');
+  await multiLevelController.cleanup();
+  await hierarchicalCoordinator.shutdown();
+  await queryController.cleanup();
+  console.log('✓ All components cleaned up\n');
+
+  console.log('=== Multi-Level Control Example Complete ===');
+}
+
+// Run example
+if (import.meta.url === `file://${process.argv[1]}`) {
+  multiLevelControlExample()
+    .then(() => {
+      console.log('\n✓ Example completed successfully');
+      process.exit(0);
+    })
+    .catch((error) => {
+      console.error('\n✗ Example failed:', error);
+      process.exit(1);
+    });
+}
+
+export { multiLevelControlExample };