Telegram Usage

{
  "comment": "Add this to ~/.clawdbot/clawdbot.json to configure the telegram-usage skill",
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_HERE",
      "customCommands": [
        {
          "command": "usage",
          "description": "Show session usage stats"
        },
        {
          "command": "stats",
          "description": "Display quota and token usage"
        }
      ]
    }
  },
  "skills": {
    "entries": {
      "telegram-usage": {
        "enabled": true
      }
    }
  },
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": null
    }
  }
}

#!/usr/bin/env node

/**
 * Telegram /usage Command Handler
 * Displays session usage statistics in a clean, formatted message
 */

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

/**
 * Format a time duration in milliseconds to human-readable string
 */
function formatDuration(ms) {
  const totalSeconds = Math.floor(ms / 1000);
  const hours = Math.floor(totalSeconds / 3600);
  const minutes = Math.floor((totalSeconds % 3600) / 60);
  
  if (hours > 0) {
    return `${hours}h ${minutes}m`;
  }
  return `${minutes}m`;
}

/**
 * Format a number with thousands separator
 */
function formatNumber(n) {
  return n.toLocaleString('en-US');
}

/**
 * Calculate percentage bar with emoji indicators
 */
function getQuotaIndicator(percentage) {
  if (percentage >= 75) return '🟢'; // Good
  if (percentage >= 50) return '🟡'; // Warning
  if (percentage >= 25) return '🟠'; // Low
  return '🔴'; // Critical
}

/**
 * Get real quota data from clawdbot models status
 */
function getRealQuotaData() {
  try {
    const output = execSync('clawdbot models status', { encoding: 'utf-8' });

    // Parse the line like: "- anthropic usage: 5h 58% left ⏱1h 1m"
    const usageMatch = output.match(/usage:\s+\d+h\s+(\d+)%\s+left\s+⏱(.+)/);

    if (usageMatch) {
      const percentage = parseInt(usageMatch[1], 10);
      const timeRemaining = usageMatch[2].trim();

      // Convert time string to milliseconds for consistency
      const timeMs = parseTimeToMs(timeRemaining);

      return {
        quotaRemaining: percentage,
        sessionTimeRemaining: timeMs,
        timeRemainingFormatted: timeRemaining
      };
    }
  } catch (error) {
    console.error('Failed to get quota data:', error.message);
  }

  // Fallback to defaults
  return {
    quotaRemaining: 0,
    sessionTimeRemaining: 0,
    timeRemainingFormatted: '0m'
  };
}

/**
 * Parse time string like "1h 1m" to milliseconds
 */
function parseTimeToMs(timeStr) {
  let totalMs = 0;

  const hourMatch = timeStr.match(/(\d+)h/);
  if (hourMatch) {
    totalMs += parseInt(hourMatch[1], 10) * 60 * 60 * 1000;
  }

  const minMatch = timeStr.match(/(\d+)m/);
  if (minMatch) {
    totalMs += parseInt(minMatch[1], 10) * 60 * 1000;
  }

  return totalMs;
}

/**
 * Get quota tracker file path
 */
function getQuotaTrackerPath() {
  const homeDir = process.env.HOME || process.env.USERPROFILE;
  return path.join(homeDir, '.clawdbot', 'quota-tracker.json');
}

/**
 * Read quota start time from tracker
 */
function getQuotaStartTime() {
  const trackerPath = getQuotaTrackerPath();

  if (!fs.existsSync(trackerPath)) {
    // Create new tracker with current time
    const quotaData = {
      startTime: Date.now(),
      resetHours: 4
    };
    try {
      fs.writeFileSync(trackerPath, JSON.stringify(quotaData, null, 2));
    } catch (error) {
      console.error('Failed to create quota tracker:', error.message);
    }
    return quotaData;
  }

  try {
    const data = JSON.parse(fs.readFileSync(trackerPath, 'utf-8'));
    return data;
  } catch (error) {
    console.error('Failed to read quota tracker:', error.message);
    return { startTime: Date.now(), resetHours: 4 };
  }
}

/**
 * Calculate time remaining until quota reset (4 hours from start)
 */
function getTimeUntilReset() {
  const quotaData = getQuotaStartTime();
  const resetHours = quotaData.resetHours || 4;
  const resetTime = quotaData.startTime + (resetHours * 60 * 60 * 1000);
  const timeRemaining = resetTime - Date.now();

  // If quota period has passed, reset it
  if (timeRemaining <= 0) {
    const trackerPath = getQuotaTrackerPath();
    const newQuotaData = {
      startTime: Date.now(),
      resetHours: resetHours
    };
    try {
      fs.writeFileSync(trackerPath, JSON.stringify(newQuotaData, null, 2));
    } catch (error) {
      console.error('Failed to reset quota tracker:', error.message);
    }
    return resetHours * 60 * 60 * 1000; // Return full period
  }

  return timeRemaining;
}

/**
 * Generate usage report message
 * @param {Object} stats - Session statistics
 * @returns {string} Formatted Telegram message
 */
function generateUsageReport(stats) {
  const {
    quotaRemaining = 85,
    sessionTimeRemaining = 14400000, // 4 hours in ms
    provider = 'anthropic'
  } = stats;

  const quotaIndicator = getQuotaIndicator(quotaRemaining);
  const timeRemaining = formatDuration(sessionTimeRemaining);

  let message = `📊 API Usage\n\n`;
  message += `🔋 Quota: ${quotaIndicator} ${quotaRemaining}%\n`;
  message += `⏱️ Resets in: ${timeRemaining}`;

  return message;
}

/**
 * Parse status/context data if provided
 */
function parseContextData(contextInfo) {
  if (!contextInfo) return null;
  
  // Extract token counts from context info
  const tokenMatch = contextInfo.match(/(\d+)\s*\/\s*(\d+)/);
  if (tokenMatch) {
    return {
      used: parseInt(tokenMatch[1]),
      total: parseInt(tokenMatch[2])
    };
  }
  return null;
}

/**
 * Main handler
 */
async function main() {
  // Parse command arguments if any
  const args = process.argv.slice(2);
  const command = args[0] || 'report';

  // Get real quota data from clawdbot
  const quotaData = getRealQuotaData();

  // Default session statistics
  // In a real implementation, these would come from the gateway API or session state
  const stats = {
    quotaRemaining: quotaData.quotaRemaining,
    sessionTimeRemaining: quotaData.sessionTimeRemaining,
    totalTokens: {
      input: 2847,
      output: 1523
    },
    contextUsage: {
      used: 1856,
      total: 4096
    },
    model: 'Claude 3.5 Haiku',
    provider: 'anthropic'
  };

  if (command === 'report') {
    const report = generateUsageReport(stats);
    console.log(report);
    process.exit(0);
  }

  if (command === 'json') {
    console.log(JSON.stringify(stats, null, 2));
    process.exit(0);
  }

  // Unknown command
  console.error(`Unknown command: ${command}`);
  process.exit(1);
}

// Export for use as module
module.exports = {
  generateUsageReport,
  formatDuration,
  formatNumber,
  getQuotaIndicator,
  parseContextData,
  getQuotaStartTime,
  getTimeUntilReset
};

// Run if invoked directly
if (require.main === module) {
  main().catch(err => {
    console.error('Error:', err.message);
    process.exit(1);
  });
}

#!/usr/bin/env node

/**
 * Session Reader for Telegram Usage Command
 * Reads actual session data from Clawdbot's session store
 */

const fs = require('fs');
const path = require('path');

/**
 * Get the session store path for the current agent
 * @param {string} agentId - Agent ID (default: 'main')
 * @returns {string} Path to sessions.json
 */
function getSessionStorePath(agentId = 'main') {
  const homeDir = process.env.HOME || process.env.USERPROFILE;
  return path.join(homeDir, '.clawdbot', 'agents', agentId, 'sessions', 'sessions.json');
}

/**
 * Get the session reset time from config
 * @param {number} atHour - Hour to reset (0-23)
 * @returns {Date} Next reset time
 */
function getNextResetTime(atHour = 4) {
  const now = new Date();
  const reset = new Date();
  reset.setHours(atHour, 0, 0, 0);
  
  // If reset time has passed today, use tomorrow
  if (reset <= now) {
    reset.setDate(reset.getDate() + 1);
  }
  
  return reset;
}

/**
 * Calculate time remaining until reset
 * @param {number} atHour - Hour to reset
 * @returns {number} Milliseconds until reset
 */
function getTimeUntilReset(atHour = 4) {
  const nextReset = getNextResetTime(atHour);
  return nextReset.getTime() - Date.now();
}

/**
 * Format duration in milliseconds
 * @param {number} ms - Milliseconds
 * @returns {string} Formatted duration
 */
function formatDuration(ms) {
  const totalSeconds = Math.floor(ms / 1000);
  const hours = Math.floor(totalSeconds / 3600);
  const minutes = Math.floor((totalSeconds % 3600) / 60);
  
  if (hours > 0) {
    return `${hours}h ${minutes}m`;
  }
  return `${minutes}m`;
}

/**
 * Read session store and extract statistics
 * @param {string} sessionKey - Session key (e.g., 'agent:main:main')
 * @param {string} agentId - Agent ID (default: 'main')
 * @returns {Object} Session statistics
 */
function readSessionStats(sessionKey, agentId = 'main') {
  const storePath = getSessionStorePath(agentId);
  
  if (!fs.existsSync(storePath)) {
    console.warn(`Session store not found at ${storePath}`);
    return null;
  }

  try {
    const store = JSON.parse(fs.readFileSync(storePath, 'utf-8'));
    const session = store[sessionKey];
    
    if (!session) {
      console.warn(`Session ${sessionKey} not found in store`);
      return null;
    }

    return {
      sessionId: session.sessionId,
      updatedAt: session.updatedAt,
      inputTokens: session.inputTokens || 0,
      outputTokens: session.outputTokens || 0,
      totalTokens: session.totalTokens || 0,
      contextTokens: session.contextTokens || 0,
      model: session.model,
      provider: session.provider
    };
  } catch (error) {
    console.error(`Error reading session store: ${error.message}`);
    return null;
  }
}

/**
 * Read conversation JSONL to get token counts
 * @param {string} transcriptPath - Path to transcript JSONL
 * @returns {Object} Token statistics
 */
function readTokensFromTranscript(transcriptPath) {
  if (!fs.existsSync(transcriptPath)) {
    return null;
  }

  try {
    const lines = fs.readFileSync(transcriptPath, 'utf-8').trim().split('\n');
    let totalInput = 0;
    let totalOutput = 0;
    
    for (const line of lines) {
      if (!line) continue;
      const entry = JSON.parse(line);
      
      if (entry.role === 'user' && entry.usage?.inputTokens) {
        totalInput += entry.usage.inputTokens;
      }
      if (entry.role === 'assistant' && entry.usage?.outputTokens) {
        totalOutput += entry.usage.outputTokens;
      }
    }

    return {
      inputTokens: totalInput,
      outputTokens: totalOutput,
      totalTokens: totalInput + totalOutput
    };
  } catch (error) {
    console.warn(`Could not parse transcript: ${error.message}`);
    return null;
  }
}

/**
 * Get transcript path for a session
 * @param {string} sessionId - Session ID
 * @param {string} agentId - Agent ID
 * @returns {string} Path to transcript
 */
function getTranscriptPath(sessionId, agentId = 'main') {
  const homeDir = process.env.HOME || process.env.USERPROFILE;
  return path.join(homeDir, '.clawdbot', 'agents', agentId, 'sessions', `${sessionId}.jsonl`);
}

/**
 * Estimate context window usage
 * @param {Object} session - Session stats
 * @param {string} model - Model name
 * @returns {Object} Context usage stats
 */
function estimateContextUsage(session, model = 'claude-3-5-haiku') {
  // Context window sizes for common models
  const contextWindows = {
    'claude-3-5-haiku': 200000,
    'claude-haiku-4-5': 200000,
    'claude-3-haiku': 200000,
    'claude-3-5-sonnet': 200000,
    'claude-3-sonnet': 200000,
    'claude-3-opus': 200000,
    'claude-opus-4': 200000,
    'gpt-4': 8192,
    'gpt-4-turbo': 128000,
    'gpt-3.5-turbo': 4096
  };

  // Try to match model name (partial matches)
  let windowSize = 4096;
  for (const [modelKey, size] of Object.entries(contextWindows)) {
    if (model.toLowerCase().includes(modelKey.toLowerCase())) {
      windowSize = size;
      break;
    }
  }

  const contextUsed = session.contextTokens || session.totalTokens || 1024;
  const percentage = Math.round((contextUsed / windowSize) * 100);

  return {
    used: contextUsed,
    total: windowSize,
    percentage: Math.min(percentage, 100) // Cap at 100%
  };
}

/**
 * Collect all usage statistics
 * @param {string} sessionKey - Session key to read
 * @param {Object} options - Options
 * @returns {Object} Comprehensive usage stats
 */
function collectUsageStats(sessionKey, options = {}) {
  const {
    agentId = 'main',
    resetHour = 4,
    quotaRemaining = null,
    provider = 'anthropic'
  } = options;

  const session = readSessionStats(sessionKey, agentId);
  
  if (!session) {
    // Return defaults if session not found
    return {
      quotaRemaining: quotaRemaining || 85,
      sessionTimeRemaining: getTimeUntilReset(resetHour),
      totalTokens: { input: 0, output: 0 },
      contextUsage: { used: 0, total: 4096 },
      model: 'Unknown',
      provider: provider,
      sessionFound: false
    };
  }

  // Try to read tokens from transcript
  const transcriptPath = getTranscriptPath(session.sessionId, agentId);
  const transcriptTokens = readTokensFromTranscript(transcriptPath);

  const totalTokens = transcriptTokens || {
    inputTokens: session.inputTokens || 0,
    outputTokens: session.outputTokens || 0,
    totalTokens: session.totalTokens || 0
  };

  const contextUsage = estimateContextUsage(session, session.model);

  return {
    quotaRemaining: quotaRemaining || 82,
    sessionTimeRemaining: getTimeUntilReset(resetHour),
    totalTokens: {
      input: totalTokens.inputTokens || 0,
      output: totalTokens.outputTokens || 0
    },
    contextUsage: {
      used: contextUsage.used,
      total: contextUsage.total
    },
    contextPercentage: contextUsage.percentage,
    model: session.model || 'Claude 3.5 Haiku',
    provider: session.provider || provider,
    sessionId: session.sessionId,
    updatedAt: session.updatedAt,
    sessionFound: true
  };
}

/**
 * Format stats for display
 * @param {Object} stats - Usage statistics
 * @returns {string} Formatted message
 */
function formatStats(stats) {
  const quotaIndicator = getQuotaIndicator(stats.quotaRemaining);
  const contextIndicator = getQuotaIndicator(100 - (stats.contextPercentage || 0));
  const timeRemaining = formatDuration(stats.sessionTimeRemaining);

  let message = '<b>📊 Session Usage Report</b>\n\n';

  message += '<b>🔋 Quota Remaining</b>\n';
  message += `${quotaIndicator} <code>${stats.quotaRemaining}%</code> of API quota\n`;
  message += `Provider: ${stats.provider}\n\n`;

  message += '<b>⏱️ Session Time</b>\n';
  message += `${timeRemaining} remaining\n`;
  message += '(resets daily at 4:00 AM)\n\n';

  message += '<b>🎯 Tokens Used</b>\n';
  const total = stats.totalTokens.input + stats.totalTokens.output;
  message += `${total.toLocaleString('en-US')} total tokens\n`;
  message += `├─ Input: ${stats.totalTokens.input.toLocaleString('en-US')}\n`;
  message += `└─ Output: ${stats.totalTokens.output.toLocaleString('en-US')}\n\n`;

  message += '<b>📦 Context Window</b>\n';
  message += `${contextIndicator} <code>${stats.contextPercentage || 0}%</code> used\n`;
  message += `${stats.contextUsage.used.toLocaleString('en-US')} / ${stats.contextUsage.total.toLocaleString('en-US')} tokens\n`;

  message += `\n<i>Model: ${stats.model}</i>`;
  if (stats.sessionId) {
    message += `\n<i>Session: ${stats.sessionId.substring(0, 8)}...</i>`;
  }

  return message;
}

/**
 * Get quota indicator emoji
 */
function getQuotaIndicator(percentage) {
  if (percentage >= 75) return '🟢';
  if (percentage >= 50) return '🟡';
  if (percentage >= 25) return '🟠';
  return '🔴';
}

// Export
module.exports = {
  getSessionStorePath,
  getNextResetTime,
  getTimeUntilReset,
  formatDuration,
  readSessionStats,
  readTokensFromTranscript,
  getTranscriptPath,
  estimateContextUsage,
  collectUsageStats,
  formatStats,
  getQuotaIndicator
};

// CLI usage
if (require.main === module) {
  const sessionKey = process.argv[2] || 'agent:main:main';
  const agentId = process.argv[3] || 'main';

  const stats = collectUsageStats(sessionKey, {
    agentId,
    resetHour: 4
  });

  if (process.argv[4] === '--json') {
    console.log(JSON.stringify(stats, null, 2));
  } else {
    console.log(formatStats(stats));
  }
}