osai-agent 4.0.0

package/src/utils/helpers.js

@@ -0,0 +1,154 @@
+// =============================================================================
+// OS AI Agent — Shared Helpers
+// =============================================================================
+
+/**
+ * Estimate token count from text (rough: ~4 chars per token)
+ */
+export const estimateTokens = (text) => Math.ceil((text || '').length / 4);
+
+/**
+ * Truncate text to a maximum character length with an ellipsis suffix
+ */
+export const truncateText = (text, maxLen = 8000) => {
+  if (!text || text.length <= maxLen) return text;
+  return text.slice(0, maxLen) + '\n...[output truncated]';
+};
+
+/**
+ * Wait for a specified number of milliseconds
+ */
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Sleep that can be interrupted when shouldCancel() returns true (e.g. user pressed Esc).
+ */
+export const cancellableSleep = async (ms, shouldCancel, stepMs = 100) => {
+  let elapsed = 0;
+  while (elapsed < ms) {
+    if (shouldCancel?.()) return false;
+    const wait = Math.min(stepMs, ms - elapsed);
+    await sleep(wait);
+    elapsed += wait;
+  }
+  return !shouldCancel?.();
+};
+
+/**
+ * Retry an async operation with exponential backoff and jitter
+ * Based on production best practices from Claude Code / Cursor research
+ */
+export const retryAsync = async (fn, { maxAttempts = 3, baseDelay = 1000, jitter = true, label = 'operation' } = {}) => {
+  let lastError = null;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return { success: true, result: await fn(attempt) };
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxAttempts - 1) {
+        // Exponential backoff with jitter to avoid thundering herd
+        const exponentialDelay = baseDelay * Math.pow(2, attempt);
+        const jitterAmount = jitter ? Math.random() * baseDelay * 0.5 : 0;
+        const delay = exponentialDelay + jitterAmount;
+        console.error(`[RETRY] ${label} attempt ${attempt + 1}/${maxAttempts}, retrying in ${Math.round(delay)}ms...`);
+        await sleep(delay);
+      }
+    }
+  }
+  return { success: false, error: lastError };
+};
+
+/**
+ * Categorize errors for appropriate handling
+ * Based on research: recoverable / requires-input / terminal / fatal
+ */
+export const categorizeError = (error) => {
+  const msg = (error?.message || '').toLowerCase();
+  
+  // Fatal errors — should stop the agent loop
+  if (msg.includes('not logged in') || msg.includes('authentication') || msg.includes('invalid token')) {
+    return { category: 'fatal', recoverable: false, userMessage: error.message };
+  }
+  
+  // Terminal errors — cannot proceed
+  if (msg.includes('maximum iterations') || msg.includes('quota') || msg.includes('rate limit')) {
+    return { category: 'terminal', recoverable: false, userMessage: error.message };
+  }
+  
+  // Requires user input — pass to LLM for re-evaluation
+  if (msg.includes('cancelled by user') || msg.includes('permission denied') || msg.includes('access denied')) {
+    return { category: 'requires-input', recoverable: true, userMessage: error.message };
+  }
+  
+  // Recoverable errors — can be retried
+  if (msg.includes('timeout') || msg.includes('econnrefused') || msg.includes('network') || msg.includes('fetch')) {
+    return { category: 'recoverable', recoverable: true, userMessage: `Temporary error: ${error.message}` };
+  }
+  
+  // Default — treat as recoverable and let the LLM adapt
+  return { category: 'recoverable', recoverable: true, userMessage: error.message };
+};
+
+/**
+ * Sanitize a string for safe shell usage (basic escaping)
+ */
+export const sanitizeForShell = (str) => {
+  if (typeof str !== 'string') return '';
+  return str.replace(/[`$\\]/g, '\\$&');
+};
+
+/**
+ * Format bytes to human-readable string
+ */
+export const formatBytes = (bytes) => {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+};
+
+/**
+ * Format milliseconds to human-readable duration
+ */
+export const formatDuration = (ms) => {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const minutes = Math.floor(ms / 60000);
+  const seconds = ((ms % 60000) / 1000).toFixed(0);
+  return `${minutes}m ${seconds}s`;
+};
+
+/**
+ * Create a promise that rejects after a timeout
+ */
+export const withTimeout = (promise, ms, label = 'Operation') => {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error(`${label} timed out after ${ms / 1000}s`)), ms)
+    ),
+  ]);
+};
+
+/**
+ * Generate a simple unique ID (timestamp + random)
+ * Used as lightweight alternative to uuid for non-cryptographic purposes
+ */
+export const generateId = (prefix = '') => {
+  const now = new Date();
+  const ts = now.getTime().toString(36);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return prefix ? `${prefix}_${ts}_${rand}` : `${ts}_${rand}`;
+};
+
+/**
+ * Simple hash function for content fingerprinting
+ */
+export const simpleHash = (str) => {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) {
+    h = Math.imul(31, h) + str.charCodeAt(i) | 0;
+  }
+  return h.toString(36);
+};

package/src/utils/logger.js

@@ -0,0 +1,81 @@
+// =============================================================================
+// OS AI Agent — Logger
+// =============================================================================
+import chalk from 'chalk';
+import { ENV_VARS } from './constants.js';
+
+const LOG_LEVELS = { debug: 0, verbose: 1, info: 2, warn: 3, error: 4, silent: 5 };
+
+let currentLevel = LOG_LEVELS.info;
+let jsonOutput = false;
+let silent = false;
+
+const subscribers = [];
+
+export function subscribeToLogs(callback) {
+  subscribers.push(callback);
+  return () => {
+    const idx = subscribers.indexOf(callback);
+    if (idx >= 0) subscribers.splice(idx, 1);
+  };
+}
+
+function notify(level, msg, data) {
+  const entry = { level, msg, data, timestamp: Date.now() };
+  subscribers.forEach(cb => { try { cb(entry); } catch {} });
+}
+
+// Configure from environment
+if (process.env[ENV_VARS.DEBUG] === 'true') {
+  currentLevel = LOG_LEVELS.debug;
+} else if (process.env[ENV_VARS.VERBOSE] === 'true') {
+  currentLevel = LOG_LEVELS.verbose;
+}
+
+if (process.env[ENV_VARS.JSON_OUTPUT] === 'true') {
+  jsonOutput = true;
+}
+
+const timestamp = () => new Date().toISOString();
+
+const formatMsg = (level, msg, data = null) => {
+  if (jsonOutput) {
+    return JSON.stringify({ level, timestamp: timestamp(), message: msg, ...(data ? { data } : {}) });
+  }
+  const prefix = chalk.hex('#414868')(`[${timestamp().slice(11, 19)}]`);
+  const levelColors = {
+    debug: chalk.hex('#565f89'),
+    verbose: chalk.hex('#7dcfff'),
+    info: chalk.hex('#7aa2f7'),
+    warn: chalk.hex('#e0af68'),
+    error: chalk.hex('#f7768e'),
+  };
+  const levelStr = levelColors[level] ? levelColors[level](`[${level.toUpperCase()}]`) : `[${level.toUpperCase()}]`;
+  const dataStr = data ? chalk.hex('#3b3f52')(` ${JSON.stringify(data)}`) : '';
+  return `${prefix} ${levelStr} ${msg}${dataStr}`;
+};
+
+export const logger = {
+  debug(msg, data) {
+    if (currentLevel <= LOG_LEVELS.debug) { if (!silent) console.error(formatMsg('debug', msg, data)); notify('debug', msg, data); }
+  },
+  verbose(msg, data) {
+    if (currentLevel <= LOG_LEVELS.verbose) { if (!silent) console.error(formatMsg('verbose', msg, data)); notify('verbose', msg, data); }
+  },
+  info(msg, data) {
+    if (currentLevel <= LOG_LEVELS.info) { if (!silent) console.error(formatMsg('info', msg, data)); notify('info', msg, data); }
+  },
+  warn(msg, data) {
+    if (currentLevel <= LOG_LEVELS.warn) { if (!silent) console.error(formatMsg('warn', msg, data)); notify('warn', msg, data); }
+  },
+  error(msg, data) {
+    if (currentLevel <= LOG_LEVELS.error) { if (!silent) console.error(formatMsg('error', msg, data)); notify('error', msg, data); }
+  },
+  setLevel(level) {
+    if (LOG_LEVELS[level] !== undefined) currentLevel = LOG_LEVELS[level];
+  },
+  setSilent(v) { silent = v; },
+  isDebug() { return currentLevel <= LOG_LEVELS.debug; },
+  isVerbose() { return currentLevel <= LOG_LEVELS.verbose; },
+  enableJson() { jsonOutput = true; },
+};

package/src/utils/sound.js

@@ -0,0 +1,33 @@
+// =============================================================================
+// OS AI Agent — System Sound Notification
+// =============================================================================
+
+/**
+ * Play a system beep sound (cross-platform: Windows, macOS, Linux)
+ * This uses the terminal bell character which works on all platforms
+ * without any external dependencies or visible output
+ */
+export const playSystemBeep = () => {
+  try {
+    // Use the terminal bell character (ASCII 0x07)
+    // This works on Windows, macOS, and Linux terminals
+    process.stdout.write('\x07');
+  } catch (error) {
+    // Silently fail if beep cannot be played
+    // This ensures the application continues normally
+  }
+};
+
+/**
+ * Play system beep only if user has been inactive for a specified time
+ * @param {number} lastActivityTimestamp - Timestamp of last user activity
+ * @param {number} inactivityThresholdMs - Threshold in milliseconds (default: 600000ms = 10min)
+ */
+export const playSystemBeepIfInactive = (lastActivityTimestamp, inactivityThresholdMs = 600000) => {
+  const now = Date.now();
+  const inactiveTime = now - lastActivityTimestamp;
+  
+  if (inactiveTime >= inactivityThresholdMs) {
+    playSystemBeep();
+  }
+};