claude-cli-advanced-starter-pack 1.1.0 → 1.8.1

package/templates/scripts/analyze-delegation-log.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * Analyze Delegation Log
+ *
+ * Analyzes Claude Code delegation logs to understand model usage,
+ * token consumption, and agent patterns.
+ *
+ * Usage:
+ *   node analyze-delegation-log.js ~/.claude/logs/delegation.jsonl
+ *   node analyze-delegation-log.js log.jsonl --cost-estimate
+ *   node analyze-delegation-log.js log.jsonl --output json
+ */
+
+import { readFileSync, existsSync } from 'fs';
+
+// Approximate costs per 1M tokens (as of 2025)
+const MODEL_COSTS = {
+  'claude-opus-4-5': { input: 15.00, output: 75.00 },
+  'claude-sonnet-4': { input: 3.00, output: 15.00 },
+  'claude-haiku': { input: 0.25, output: 1.25 },
+  'default': { input: 3.00, output: 15.00 },
+};
+
+class DelegationAnalyzer {
+  constructor(logPath, options = {}) {
+    this.logPath = logPath;
+    this.options = options;
+    this.entries = [];
+    this.analysis = {
+      models: {},
+      agents: {},
+      tools: {},
+      sessions: {},
+      timeline: [],
+    };
+  }
+
+  async analyze() {
+    console.log(`\n📊 Analyzing delegation log: ${this.logPath}\n`);
+
+    if (!existsSync(this.logPath)) {
+      console.error(`Error: File not found: ${this.logPath}`);
+      process.exit(1);
+    }
+
+    await this.parseLog();
+    await this.computeMetrics();
+
+    if (this.options.output === 'json') {
+      this.outputJson();
+    } else {
+      this.outputText();
+    }
+  }
+
+  async parseLog() {
+    const content = readFileSync(this.logPath, 'utf8');
+    const lines = content.split('\n').filter(line => line.trim());
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        this.entries.push(entry);
+      } catch (e) {
+        // Skip invalid lines
+      }
+    }
+
+    console.log(`Parsed ${this.entries.length} log entries\n`);
+  }
+
+  async computeMetrics() {
+    for (const entry of this.entries) {
+      // Track by model
+      const model = entry.model || 'unknown';
+      if (!this.analysis.models[model]) {
+        this.analysis.models[model] = {
+          calls: 0,
+          inputTokens: 0,
+          outputTokens: 0,
+          errors: 0,
+          avgLatency: 0,
+          latencies: [],
+        };
+      }
+
+      const modelStats = this.analysis.models[model];
+      modelStats.calls++;
+      modelStats.inputTokens += entry.inputTokens || 0;
+      modelStats.outputTokens += entry.outputTokens || 0;
+      if (entry.error) modelStats.errors++;
+      if (entry.latencyMs) modelStats.latencies.push(entry.latencyMs);
+
+      // Track by agent type
+      const agentType = entry.agentType || entry.subagentType || 'main';
+      if (!this.analysis.agents[agentType]) {
+        this.analysis.agents[agentType] = {
+          invocations: 0,
+          totalTokens: 0,
+          avgTokensPerCall: 0,
+        };
+      }
+
+      const agentStats = this.analysis.agents[agentType];
+      agentStats.invocations++;
+      agentStats.totalTokens += (entry.inputTokens || 0) + (entry.outputTokens || 0);
+
+      // Track by tool
+      if (entry.tool) {
+        if (!this.analysis.tools[entry.tool]) {
+          this.analysis.tools[entry.tool] = { calls: 0, errors: 0 };
+        }
+        this.analysis.tools[entry.tool].calls++;
+        if (entry.error) this.analysis.tools[entry.tool].errors++;
+      }
+
+      // Track by session
+      const sessionId = entry.sessionId || 'default';
+      if (!this.analysis.sessions[sessionId]) {
+        this.analysis.sessions[sessionId] = {
+          calls: 0,
+          tokens: 0,
+          start: entry.timestamp,
+          end: entry.timestamp,
+        };
+      }
+
+      const session = this.analysis.sessions[sessionId];
+      session.calls++;
+      session.tokens += (entry.inputTokens || 0) + (entry.outputTokens || 0);
+      if (entry.timestamp > session.end) session.end = entry.timestamp;
+    }
+
+    // Compute averages
+    for (const model of Object.keys(this.analysis.models)) {
+      const stats = this.analysis.models[model];
+      if (stats.latencies.length > 0) {
+        stats.avgLatency = Math.round(
+          stats.latencies.reduce((a, b) => a + b, 0) / stats.latencies.length
+        );
+      }
+      delete stats.latencies;
+    }
+
+    for (const agent of Object.keys(this.analysis.agents)) {
+      const stats = this.analysis.agents[agent];
+      stats.avgTokensPerCall = Math.round(stats.totalTokens / stats.invocations);
+    }
+  }
+
+  estimateCost() {
+    let totalCost = 0;
+    const breakdown = {};
+
+    for (const [model, stats] of Object.entries(this.analysis.models)) {
+      const costs = MODEL_COSTS[model] || MODEL_COSTS['default'];
+      const inputCost = (stats.inputTokens / 1_000_000) * costs.input;
+      const outputCost = (stats.outputTokens / 1_000_000) * costs.output;
+      const modelCost = inputCost + outputCost;
+
+      breakdown[model] = {
+        inputCost: inputCost.toFixed(4),
+        outputCost: outputCost.toFixed(4),
+        totalCost: modelCost.toFixed(4),
+      };
+
+      totalCost += modelCost;
+    }
+
+    return { breakdown, totalCost: totalCost.toFixed(4) };
+  }
+
+  outputText() {
+    console.log('='.repeat(70));
+    console.log('                    DELEGATION LOG ANALYSIS');
+    console.log('='.repeat(70));
+
+    // Model usage
+    console.log('\n📊 Model Usage\n');
+    console.log('Model                      Calls     Input Tokens    Output Tokens    Errors');
+    console.log('-'.repeat(70));
+
+    for (const [model, stats] of Object.entries(this.analysis.models)) {
+      const modelName = model.padEnd(24);
+      const calls = stats.calls.toString().padStart(6);
+      const input = stats.inputTokens.toLocaleString().padStart(15);
+      const output = stats.outputTokens.toLocaleString().padStart(16);
+      const errors = stats.errors.toString().padStart(8);
+      console.log(`${modelName}${calls}${input}${output}${errors}`);
+    }
+
+    // Agent usage
+    console.log('\n🤖 Agent Types\n');
+    console.log('Agent Type              Invocations    Total Tokens    Avg Tokens/Call');
+    console.log('-'.repeat(70));
+
+    for (const [agent, stats] of Object.entries(this.analysis.agents)) {
+      const agentName = agent.padEnd(22);
+      const invocations = stats.invocations.toString().padStart(12);
+      const tokens = stats.totalTokens.toLocaleString().padStart(15);
+      const avg = stats.avgTokensPerCall.toLocaleString().padStart(17);
+      console.log(`${agentName}${invocations}${tokens}${avg}`);
+    }
+
+    // Tool usage (top 10)
+    const toolEntries = Object.entries(this.analysis.tools)
+      .sort((a, b) => b[1].calls - a[1].calls)
+      .slice(0, 10);
+
+    if (toolEntries.length > 0) {
+      console.log('\n🔧 Top 10 Tools\n');
+      console.log('Tool                           Calls    Errors');
+      console.log('-'.repeat(50));
+
+      for (const [tool, stats] of toolEntries) {
+        const toolName = tool.padEnd(30);
+        const calls = stats.calls.toString().padStart(6);
+        const errors = stats.errors.toString().padStart(9);
+        console.log(`${toolName}${calls}${errors}`);
+      }
+    }
+
+    // Cost estimate
+    if (this.options.costEstimate) {
+      const cost = this.estimateCost();
+
+      console.log('\n💰 Cost Estimate\n');
+      console.log('Model                       Input Cost    Output Cost    Total Cost');
+      console.log('-'.repeat(70));
+
+      for (const [model, costs] of Object.entries(cost.breakdown)) {
+        const modelName = model.padEnd(26);
+        const input = `$${costs.inputCost}`.padStart(12);
+        const output = `$${costs.outputCost}`.padStart(14);
+        const total = `$${costs.totalCost}`.padStart(13);
+        console.log(`${modelName}${input}${output}${total}`);
+      }
+
+      console.log('-'.repeat(70));
+      console.log(`${'TOTAL'.padEnd(26)}${''.padStart(26)}$${cost.totalCost}`.padStart(13));
+    }
+
+    // Summary
+    const totalCalls = Object.values(this.analysis.models)
+      .reduce((acc, m) => acc + m.calls, 0);
+    const totalTokens = Object.values(this.analysis.models)
+      .reduce((acc, m) => acc + m.inputTokens + m.outputTokens, 0);
+    const totalErrors = Object.values(this.analysis.models)
+      .reduce((acc, m) => acc + m.errors, 0);
+
+    console.log('\n' + '='.repeat(70));
+    console.log('SUMMARY');
+    console.log('='.repeat(70));
+    console.log(`\n   Total API Calls: ${totalCalls.toLocaleString()}`);
+    console.log(`   Total Tokens:    ${totalTokens.toLocaleString()}`);
+    console.log(`   Error Rate:      ${((totalErrors / totalCalls) * 100).toFixed(2)}%`);
+    console.log(`   Sessions:        ${Object.keys(this.analysis.sessions).length}`);
+    console.log('\n' + '='.repeat(70) + '\n');
+  }
+
+  outputJson() {
+    const output = {
+      analyzedAt: new Date().toISOString(),
+      logPath: this.logPath,
+      totalEntries: this.entries.length,
+      analysis: this.analysis,
+    };
+
+    if (this.options.costEstimate) {
+      output.costEstimate = this.estimateCost();
+    }
+
+    console.log(JSON.stringify(output, null, 2));
+  }
+}
+
+// CLI entry point
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0].startsWith('--')) {
+    console.error('Usage: node analyze-delegation-log.js <log-file> [options]');
+    console.error('Options:');
+    console.error('  --cost-estimate    Include cost estimate');
+    console.error('  --output json      Output as JSON');
+    process.exit(1);
+  }
+
+  const logPath = args[0];
+  const options = {
+    costEstimate: args.includes('--cost-estimate'),
+    output: args.includes('--output') ? args[args.indexOf('--output') + 1] : 'text',
+  };
+
+  const analyzer = new DelegationAnalyzer(logPath, options);
+  await analyzer.analyze();
+}
+
+main().catch(console.error);

package/templates/scripts/autonomous-decision-logger.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * Autonomous Decision Logger
+ *
+ * Creates JSONL audit trail for agent decisions.
+ * Tracks reasoning, confidence, and outcomes.
+ *
+ * Usage:
+ *   // Import in your hook or script
+ *   import { DecisionLogger } from './autonomous-decision-logger.js';
+ *
+ *   const logger = new DecisionLogger('.claude/logs/decisions.jsonl');
+ *   logger.logDecision({
+ *     agent: 'deployment-checker',
+ *     decision: 'deploy',
+ *     reasoning: 'All tests passed, no conflicts',
+ *     confidence: 0.95,
+ *   });
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+
+export class DecisionLogger {
+  constructor(logPath = '.claude/logs/decisions.jsonl') {
+    this.logPath = resolve(process.cwd(), logPath);
+    this.sessionId = this.generateSessionId();
+    this.ensureLogDirectory();
+  }
+
+  generateSessionId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `${timestamp}-${random}`;
+  }
+
+  ensureLogDirectory() {
+    const dir = dirname(this.logPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * Log a decision with full context
+   *
+   * @param {Object} decision
+   * @param {string} decision.agent - Agent/component making decision
+   * @param {string} decision.decision - The decision made
+   * @param {string} decision.reasoning - Why this decision was made
+   * @param {number} decision.confidence - Confidence level 0-1
+   * @param {Object} [decision.context] - Additional context
+   * @param {string} [decision.outcome] - Result (success/failure/pending)
+   * @param {Array} [decision.alternatives] - Other options considered
+   */
+  logDecision(decision) {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      sessionId: this.sessionId,
+      pid: process.pid,
+      ...decision,
+    };
+
+    this.writeEntry(entry);
+    return entry;
+  }
+
+  /**
+   * Log an action taken by an agent
+   */
+  logAction(agent, action, details = {}) {
+    return this.logDecision({
+      agent,
+      type: 'action',
+      decision: action,
+      ...details,
+    });
+  }
+
+  /**
+   * Log an observation or analysis
+   */
+  logObservation(agent, observation, details = {}) {
+    return this.logDecision({
+      agent,
+      type: 'observation',
+      decision: observation,
+      ...details,
+    });
+  }
+
+  /**
+   * Log an error or failure
+   */
+  logError(agent, error, context = {}) {
+    return this.logDecision({
+      agent,
+      type: 'error',
+      decision: 'error',
+      reasoning: error.message || error,
+      outcome: 'failure',
+      context: {
+        ...context,
+        stack: error.stack,
+      },
+    });
+  }
+
+  /**
+   * Log a phase transition
+   */
+  logPhaseTransition(fromPhase, toPhase, reason, validation = {}) {
+    return this.logDecision({
+      agent: 'phase-controller',
+      type: 'phase_transition',
+      decision: `${fromPhase} -> ${toPhase}`,
+      reasoning: reason,
+      context: { fromPhase, toPhase, validation },
+      outcome: 'success',
+    });
+  }
+
+  /**
+   * Log agent spawn/delegation
+   */
+  logDelegation(parentAgent, childAgent, task, options = {}) {
+    return this.logDecision({
+      agent: parentAgent,
+      type: 'delegation',
+      decision: `spawn:${childAgent}`,
+      reasoning: `Delegating: ${task}`,
+      context: {
+        childAgent,
+        task,
+        model: options.model,
+        runInBackground: options.runInBackground,
+      },
+    });
+  }
+
+  writeEntry(entry) {
+    const line = JSON.stringify(entry) + '\n';
+    appendFileSync(this.logPath, line);
+  }
+
+  /**
+   * Read all decisions for current session
+   */
+  getSessionDecisions() {
+    if (!existsSync(this.logPath)) return [];
+
+    const content = readFileSync(this.logPath, 'utf8');
+    return content
+      .split('\n')
+      .filter(line => line.trim())
+      .map(line => JSON.parse(line))
+      .filter(entry => entry.sessionId === this.sessionId);
+  }
+
+  /**
+   * Get summary statistics
+   */
+  getSummary() {
+    const decisions = this.getSessionDecisions();
+
+    const summary = {
+      sessionId: this.sessionId,
+      totalDecisions: decisions.length,
+      byType: {},
+      byAgent: {},
+      byOutcome: {},
+      avgConfidence: 0,
+    };
+
+    let confidenceSum = 0;
+    let confidenceCount = 0;
+
+    for (const d of decisions) {
+      // Count by type
+      const type = d.type || 'decision';
+      summary.byType[type] = (summary.byType[type] || 0) + 1;
+
+      // Count by agent
+      summary.byAgent[d.agent] = (summary.byAgent[d.agent] || 0) + 1;
+
+      // Count by outcome
+      if (d.outcome) {
+        summary.byOutcome[d.outcome] = (summary.byOutcome[d.outcome] || 0) + 1;
+      }
+
+      // Average confidence
+      if (typeof d.confidence === 'number') {
+        confidenceSum += d.confidence;
+        confidenceCount++;
+      }
+    }
+
+    if (confidenceCount > 0) {
+      summary.avgConfidence = (confidenceSum / confidenceCount).toFixed(2);
+    }
+
+    return summary;
+  }
+}
+
+// CLI mode - print summary if run directly
+async function main() {
+  const args = process.argv.slice(2);
+  const logPath = args[0] || '.claude/logs/decisions.jsonl';
+
+  if (!existsSync(logPath)) {
+    console.log(`No log file found at: ${logPath}`);
+    console.log('\nUsage: node autonomous-decision-logger.js [log-path]');
+    console.log('\nTo create logs, import DecisionLogger in your code:');
+    console.log("  import { DecisionLogger } from './autonomous-decision-logger.js';");
+    console.log("  const logger = new DecisionLogger();");
+    console.log("  logger.logDecision({ agent: 'my-agent', decision: 'proceed', confidence: 0.9 });");
+    return;
+  }
+
+  // Read and summarize log
+  const content = readFileSync(logPath, 'utf8');
+  const entries = content
+    .split('\n')
+    .filter(line => line.trim())
+    .map(line => JSON.parse(line));
+
+  console.log('\n📋 Decision Log Summary\n');
+  console.log(`Log file: ${logPath}`);
+  console.log(`Total entries: ${entries.length}`);
+
+  // Group by session
+  const sessions = {};
+  for (const entry of entries) {
+    const sid = entry.sessionId || 'unknown';
+    if (!sessions[sid]) {
+      sessions[sid] = [];
+    }
+    sessions[sid].push(entry);
+  }
+
+  console.log(`Sessions: ${Object.keys(sessions).length}`);
+
+  // Show last 10 decisions
+  console.log('\n📜 Last 10 Decisions:\n');
+  const recent = entries.slice(-10);
+  for (const entry of recent) {
+    const time = new Date(entry.timestamp).toLocaleTimeString();
+    const conf = entry.confidence ? ` (${(entry.confidence * 100).toFixed(0)}%)` : '';
+    console.log(`  [${time}] ${entry.agent}: ${entry.decision}${conf}`);
+    if (entry.reasoning) {
+      console.log(`           └─ ${entry.reasoning.substring(0, 60)}`);
+    }
+  }
+
+  // By type
+  const typeCount = {};
+  for (const entry of entries) {
+    const type = entry.type || 'decision';
+    typeCount[type] = (typeCount[type] || 0) + 1;
+  }
+
+  console.log('\n📊 By Type:');
+  for (const [type, count] of Object.entries(typeCount).sort((a, b) => b[1] - a[1])) {
+    console.log(`  ${type}: ${count}`);
+  }
+
+  console.log('');
+}
+
+// Export for use as module
+export default DecisionLogger;
+
+// Run CLI if called directly
+if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}`) {
+  main().catch(console.error);
+}