ai-control-center 1.15.2

package/lib/utils/errors.js

@@ -0,0 +1,116 @@
+/**
+ * Structured Error Codes for AI Control Center.
+ *
+ * Error Code Reference:
+ *   E001  AI_TIMEOUT             — AI subprocess exceeded its time limit
+ *   E002  AI_RATE_LIMIT          — Temporary rate limit (429) from AI provider
+ *   E003  AI_CAPACITY            — Daily quota/capacity exhausted for AI provider
+ *   E004  AI_CIRCUIT_OPEN        — Circuit breaker is OPEN for provider, skipping
+ *   E005  PIPELINE_STALL         — Pipeline stage stuck with no progress
+ *   E006  TOKEN_BUDGET           — Token budget exceeded for pipeline run
+ *   E007  CHECKPOINT_CORRUPT     — Checkpoint file failed integrity check
+ *   E008  STATE_WRITE_FAIL       — Failed to write state file atomically
+ *   E009  SESSION_CORRUPT        — AI session file is corrupt or unreadable
+ *   E010  PROVIDER_CHAIN_EXHAUSTED — All models/providers in fallback chain failed
+ *   E011  RESPONSE_INVALID       — AI response failed validation (empty/truncated)
+ *   E012  GEMINI_HUNG            — Gemini process produced no output (watchdog kill)
+ */
+
+export const ErrorCodes = {
+  AI_TIMEOUT:                'E001',
+  AI_RATE_LIMIT:             'E002',
+  AI_CAPACITY:               'E003',
+  AI_CIRCUIT_OPEN:           'E004',
+  PIPELINE_STALL:            'E005',
+  TOKEN_BUDGET:              'E006',
+  CHECKPOINT_CORRUPT:        'E007',
+  STATE_WRITE_FAIL:          'E008',
+  SESSION_CORRUPT:           'E009',
+  PROVIDER_CHAIN_EXHAUSTED:  'E010',
+  RESPONSE_INVALID:          'E011',
+  GEMINI_HUNG:               'E012',
+};
+
+/**
+ * Base error class for AICC with structured error code.
+ */
+export class AIControlError extends Error {
+  constructor(code, message) {
+    super(`[${code}] ${message}`);
+    this.name = 'AIControlError';
+    this.code = code;
+  }
+}
+
+/**
+ * AI subprocess exceeded its configured timeout.
+ */
+export class AITimeoutError extends AIControlError {
+  constructor(agent, timeoutMs, command = '') {
+    super(ErrorCodes.AI_TIMEOUT, `TIMEOUT: ${agent} hung after ${Math.round(timeoutMs / 1000)}s`);
+    this.name = 'AITimeoutError';
+    this.agent = agent;
+    this.timeoutMs = timeoutMs;
+    this.command = command;
+  }
+}
+
+/**
+ * Circuit breaker is OPEN — provider is temporarily blocked.
+ */
+export class CircuitOpenError extends AIControlError {
+  constructor(provider) {
+    super(ErrorCodes.AI_CIRCUIT_OPEN, `Circuit breaker OPEN for ${provider} — skipping`);
+    this.name = 'CircuitOpenError';
+    this.provider = provider;
+  }
+}
+
+/**
+ * Token budget exceeded for a pipeline run.
+ */
+export class TokenBudgetError extends AIControlError {
+  constructor(used, limit, featureId) {
+    super(ErrorCodes.TOKEN_BUDGET, `Token budget exceeded: ${used.toLocaleString()}/${limit.toLocaleString()} for ${featureId}`);
+    this.name = 'TokenBudgetError';
+    this.used = used;
+    this.limit = limit;
+    this.featureId = featureId;
+  }
+}
+
+/**
+ * Checkpoint integrity check failed.
+ */
+export class CheckpointCorruptError extends AIControlError {
+  constructor(featureId, stage) {
+    super(ErrorCodes.CHECKPOINT_CORRUPT, `Checkpoint corrupt for ${featureId}/${stage}`);
+    this.name = 'CheckpointCorruptError';
+    this.featureId = featureId;
+    this.stage = stage;
+  }
+}
+
+/**
+ * AI response failed validation (empty, truncated, missing required sections).
+ */
+export class ResponseValidationError extends AIControlError {
+  constructor(agent, reason) {
+    super(ErrorCodes.RESPONSE_INVALID, `${agent} response validation failed: ${reason}`);
+    this.name = 'ResponseValidationError';
+    this.agent = agent;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Pipeline stalled — no stage change for extended period.
+ */
+export class PipelineStallError extends AIControlError {
+  constructor(stage, minutesElapsed) {
+    super(ErrorCodes.PIPELINE_STALL, `Pipeline stalled on "${stage}" for ${minutesElapsed} minutes`);
+    this.name = 'PipelineStallError';
+    this.stage = stage;
+    this.minutesElapsed = minutesElapsed;
+  }
+}

package/lib/utils/format.js

@@ -0,0 +1,134 @@
+/**
+ * lib/utils/format.js — Per-platform message formatting.
+ *
+ * The AI always outputs CommonMark-style markdown. This module converts
+ * that to whatever each chat platform expects before sending.
+ *
+ * Supported platforms: telegram | whatsapp | twitch | plain
+ */
+
+// ─── Telegram ─────────────────────────────────────────────────────────────────
+// Telegram HTML mode is the most reliable:
+// - Doesn't require escaping every special char (unlike MarkdownV2)
+// - Supports: <b> <i> <s> <u> <code> <pre> <a>
+
+/**
+ * Convert CommonMark markdown to Telegram HTML.
+ * Handles the most common AI output patterns.
+ */
+export function markdownToTelegramHTML(text) {
+  if (!text) return '';
+
+  let result = text;
+
+  // 1. Extract and protect code blocks first (avoid mangling their content)
+  const codeBlocks = [];
+  result = result.replace(/```(\w*)\n?([\s\S]*?)```/g, (_, lang, code) => {
+    const idx = codeBlocks.length;
+    codeBlocks.push(`<pre><code>${escapeHTML(code.trim())}</code></pre>`);
+    return `\x00CODE${idx}\x00`;
+  });
+
+  // 2. Protect inline code
+  const inlineCodes = [];
+  result = result.replace(/`([^`\n]+)`/g, (_, code) => {
+    const idx = inlineCodes.length;
+    inlineCodes.push(`<code>${escapeHTML(code)}</code>`);
+    return `\x00INLINE${idx}\x00`;
+  });
+
+  // 3. Escape HTML special chars in regular text
+  result = escapeHTML(result);
+
+  // 4. Headers → bold line
+  result = result.replace(/^#{1,3} (.+)$/gm, '<b>$1</b>');
+
+  // 5. Bold: **text** or __text__
+  result = result.replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>');
+  result = result.replace(/__([^_\n]+)__/g, '<b>$1</b>');
+
+  // 6. Italic: *text* or _text_ (single, not touching word boundaries weirdly)
+  result = result.replace(/\*([^*\n]+)\*/g, '<i>$1</i>');
+  result = result.replace(/(?<!\w)_([^_\n]+)_(?!\w)/g, '<i>$1</i>');
+
+  // 7. Strikethrough: ~~text~~
+  result = result.replace(/~~([^~\n]+)~~/g, '<s>$1</s>');
+
+  // 8. Horizontal rules → divider
+  result = result.replace(/^[-*_]{3,}$/gm, '─────────────────');
+
+  // 9. Restore code blocks and inline code
+  result = result.replace(/\x00CODE(\d+)\x00/g, (_, i) => codeBlocks[+i]);
+  result = result.replace(/\x00INLINE(\d+)\x00/g, (_, i) => inlineCodes[+i]);
+
+  return result.trim();
+}
+
+function escapeHTML(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+// ─── WhatsApp ─────────────────────────────────────────────────────────────────
+// WhatsApp uses: *bold*, _italic_, ~strikethrough~, ```code```
+
+export function markdownToWhatsApp(text) {
+  if (!text) return '';
+  let result = text;
+
+  // Code blocks stay as-is (WhatsApp supports ```)
+  // Bold: **text** → *text*
+  result = result.replace(/\*\*([^*\n]+)\*\*/g, '*$1*');
+  result = result.replace(/__([^_\n]+)__/g, '*$1*');
+  // Italic: *text* (single) → _text_
+  result = result.replace(/(?<![*])\*([^*\n]+)\*(?![*])/g, '_$1_');
+  // Strikethrough: ~~text~~ → ~text~
+  result = result.replace(/~~([^~\n]+)~~/g, '~$1~');
+  // Headers → bold
+  result = result.replace(/^#{1,3} (.+)$/gm, '*$1*');
+
+  return result.trim();
+}
+
+// ─── Twitch ───────────────────────────────────────────────────────────────────
+// Twitch chat has no markdown — strip all formatting, keep text clean
+
+export function markdownToTwitch(text) {
+  if (!text) return '';
+  return text
+    .replace(/```[\w]*\n?([\s\S]*?)```/g, '$1')  // code blocks → plain
+    .replace(/`([^`]+)`/g, '$1')                  // inline code → plain
+    .replace(/\*\*([^*]+)\*\*/g, '$1')            // bold → plain
+    .replace(/__([^_]+)__/g, '$1')
+    .replace(/\*([^*]+)\*/g, '$1')
+    .replace(/_([^_]+)_/g, '$1')
+    .replace(/~~([^~]+)~~/g, '$1')
+    .replace(/^#{1,6} /gm, '')                    // headers → plain
+    .replace(/^\s*[-*+] /gm, '• ')                // bullets → •
+    .trim();
+}
+
+// ─── Platform dispatcher ─────────────────────────────────────────────────────
+
+/**
+ * Format AI markdown output for a specific chat platform.
+ * Returns { text, options } ready to pass to the platform SDK.
+ *
+ * @param {string} text     Raw markdown from AI
+ * @param {string} platform 'telegram' | 'whatsapp' | 'twitch' | 'plain'
+ * @returns {{ text: string, options: object }}
+ */
+export function formatForPlatform(text, platform = 'telegram') {
+  switch (platform) {
+    case 'telegram':
+      return { text: markdownToTelegramHTML(text), options: { parse_mode: 'HTML' } };
+    case 'whatsapp':
+      return { text: markdownToWhatsApp(text), options: {} };
+    case 'twitch':
+      return { text: markdownToTwitch(text), options: {} };
+    default:
+      return { text, options: {} };
+  }
+}