@soleri/core 2.10.0 → 2.12.0

package/src/chat/notifications.ts

@@ -0,0 +1,164 @@
+/**
+ * Notification Engine — pluggable background polling with debounce.
+ *
+ * Generic notification system for chat transports. Register check functions
+ * that run at configurable intervals. Built-in debounce prevents spam.
+ *
+ * Transport-specific delivery (Telegram, Discord, etc.) is handled via
+ * the onNotify callback.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface NotificationCheck {
+  /** Unique check ID. */
+  id: string;
+  /** Human-readable label. */
+  label: string;
+  /** The check function. Returns null if nothing to notify, or a message string. */
+  check: () => Promise<string | null>;
+  /** Cooldown between notifications for this check (ms). Default: 4 hours. */
+  cooldownMs?: number;
+  /** Optional time window — only run during these hours (0-23). */
+  activeHours?: { start: number; end: number };
+}
+
+export interface NotificationEngineConfig {
+  /** Polling interval in ms. Default: 30 minutes. */
+  intervalMs?: number;
+  /** Callback to deliver a notification. */
+  onNotify: (checkId: string, message: string) => Promise<void>;
+  /** Default cooldown for checks that don't specify one. Default: 4 hours. */
+  defaultCooldownMs?: number;
+}
+
+export interface NotificationStats {
+  /** Number of registered checks. */
+  checks: number;
+  /** Whether the engine is running. */
+  running: boolean;
+  /** Total notifications sent. */
+  sent: number;
+  /** Last poll timestamp. */
+  lastPollAt: number | null;
+}
+
+// ─── Engine ───────────────────────────────────────────────────────────
+
+const DEFAULT_INTERVAL_MS = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_COOLDOWN_MS = 4 * 60 * 60 * 1000; // 4 hours
+
+export class NotificationEngine {
+  private checks = new Map<string, NotificationCheck>();
+  private lastNotified = new Map<string, number>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private sent = 0;
+  private lastPollAt: number | null = null;
+  private readonly intervalMs: number;
+  private readonly defaultCooldownMs: number;
+  private readonly onNotify: (checkId: string, message: string) => Promise<void>;
+
+  constructor(config: NotificationEngineConfig) {
+    this.intervalMs = config.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.defaultCooldownMs = config.defaultCooldownMs ?? DEFAULT_COOLDOWN_MS;
+    this.onNotify = config.onNotify;
+  }
+
+  /**
+   * Register a notification check.
+   */
+  register(check: NotificationCheck): void {
+    this.checks.set(check.id, check);
+  }
+
+  /**
+   * Unregister a check.
+   */
+  unregister(id: string): boolean {
+    return this.checks.delete(id);
+  }
+
+  /**
+   * Start the polling loop. Runs an initial check after a short delay.
+   */
+  start(): void {
+    if (this.timer) return; // Already running
+
+    // Initial check after 10 seconds
+    setTimeout(() => this.poll(), 10_000);
+
+    this.timer = setInterval(() => this.poll(), this.intervalMs);
+  }
+
+  /**
+   * Stop the polling loop.
+   */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Run all checks once (called automatically by the polling loop).
+   */
+  async poll(): Promise<number> {
+    this.lastPollAt = Date.now();
+    let notified = 0;
+
+    for (const [id, check] of this.checks) {
+      try {
+        // Time window check
+        if (check.activeHours) {
+          const hour = new Date().getHours();
+          const { start, end } = check.activeHours;
+          if (start <= end) {
+            if (hour < start || hour >= end) continue;
+          } else {
+            // Wraps midnight (e.g., 22-6)
+            if (hour < start && hour >= end) continue;
+          }
+        }
+
+        // Cooldown check
+        if (!this.shouldNotify(id, check.cooldownMs ?? this.defaultCooldownMs)) {
+          continue;
+        }
+
+        const message = await check.check();
+        if (message) {
+          await this.onNotify(id, message);
+          this.lastNotified.set(id, Date.now());
+          this.sent++;
+          notified++;
+        }
+      } catch {
+        // Individual check failure is non-critical
+      }
+    }
+
+    return notified;
+  }
+
+  /**
+   * Get engine stats.
+   */
+  stats(): NotificationStats {
+    return {
+      checks: this.checks.size,
+      running: this.timer !== null,
+      sent: this.sent,
+      lastPollAt: this.lastPollAt,
+    };
+  }
+
+  /**
+   * Check if enough time has passed since last notification for this check.
+   */
+  private shouldNotify(checkId: string, cooldownMs: number): boolean {
+    const last = this.lastNotified.get(checkId);
+    if (!last) return true;
+    return Date.now() - last >= cooldownMs;
+  }
+}

package/src/chat/output-compressor.ts

@@ -0,0 +1,116 @@
+/**
+ * Output Compressor — compress verbose tool outputs for chat contexts.
+ *
+ * Unlike Salvador's 30+ domain-specific compressors, this provides:
+ * 1. A generic JSON compressor (extracts key fields, truncates arrays)
+ * 2. A registry for domain-specific compressors (pluggable)
+ *
+ * Domain packs can register their own compressors for their tools.
+ */
+
+import type { OutputCompressor } from './agent-loop-types.js';
+
+const DEFAULT_MAX_LENGTH = 4000;
+const DEFAULT_MAX_ARRAY_ITEMS = 5;
+const DEFAULT_MAX_STRING_LENGTH = 500;
+
+// ─── Compressor Registry ────────────────────────────────────────────
+
+type ToolCompressor = (output: string, maxLength: number) => string;
+
+const compressorRegistry = new Map<string, ToolCompressor>();
+
+/**
+ * Register a compressor for a specific tool name (or prefix).
+ */
+export function registerCompressor(toolNameOrPrefix: string, compressor: ToolCompressor): void {
+  compressorRegistry.set(toolNameOrPrefix, compressor);
+}
+
+/**
+ * Clear all registered compressors.
+ */
+export function clearCompressors(): void {
+  compressorRegistry.clear();
+}
+
+// ─── Generic Compressor ─────────────────────────────────────────────
+
+/**
+ * Create a generic output compressor. Uses registered compressors for known tools,
+ * falls back to JSON-aware truncation.
+ */
+export function createOutputCompressor(options?: {
+  maxLength?: number;
+  maxArrayItems?: number;
+  maxStringLength?: number;
+}): OutputCompressor {
+  const maxLength = options?.maxLength ?? DEFAULT_MAX_LENGTH;
+  const maxArrayItems = options?.maxArrayItems ?? DEFAULT_MAX_ARRAY_ITEMS;
+  const maxStringLength = options?.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;
+
+  return (toolName: string, output: string, overrideMax?: number) => {
+    const limit = overrideMax ?? maxLength;
+
+    // Check registered compressors (exact match, then prefix match)
+    const exact = compressorRegistry.get(toolName);
+    if (exact) return exact(output, limit);
+
+    for (const [prefix, compressor] of compressorRegistry) {
+      if (toolName.startsWith(prefix)) {
+        return compressor(output, limit);
+      }
+    }
+
+    // Already short enough
+    if (output.length <= limit) return output;
+
+    // Try JSON-aware compression
+    try {
+      const parsed = JSON.parse(output);
+      const compressed = compressValue(parsed, maxArrayItems, maxStringLength);
+      const result = JSON.stringify(compressed, null, 2);
+      if (result.length <= limit) return result;
+      return result.slice(0, limit) + '\n... (compressed, truncated)';
+    } catch {
+      // Not JSON — plain text truncation
+      return output.slice(0, limit) + '\n... (truncated)';
+    }
+  };
+}
+
+// ─── JSON Compression ───────────────────────────────────────────────
+
+function compressValue(value: unknown, maxArrayItems: number, maxStringLength: number): unknown {
+  if (value === null || value === undefined) return value;
+
+  if (typeof value === 'string') {
+    if (value.length > maxStringLength) {
+      return value.slice(0, maxStringLength) + `... (+${value.length - maxStringLength} chars)`;
+    }
+    return value;
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+
+  if (Array.isArray(value)) {
+    const truncated = value
+      .slice(0, maxArrayItems)
+      .map((item) => compressValue(item, maxArrayItems, maxStringLength));
+    if (value.length > maxArrayItems) {
+      truncated.push(`... +${value.length - maxArrayItems} more`);
+    }
+    return truncated;
+  }
+
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      result[key] = compressValue(val, maxArrayItems, maxStringLength);
+    }
+    return result;
+  }
+
+  return value;
+}

package/src/chat/queue.ts

@@ -0,0 +1,208 @@
+/**
+ * Message Queue — disk-based message passing for zero-cost chat relay.
+ *
+ * The queue bot writes incoming messages to inbox/. Claude Code (or any
+ * processor) reads them, generates responses, and writes to outbox/.
+ * The outbox poller sends replies back through the chat transport.
+ *
+ * Directory structure:
+ *   ~/.{agentId}/queue/
+ *     inbox/    ← bot writes, processor reads
+ *     outbox/   ← processor writes, bot reads and sends
+ */
+
+import {
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+  unlinkSync,
+  existsSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface QueuedMessage {
+  /** Unique message ID: `{chatId}-{timestamp}`. */
+  id: string;
+  /** Chat/channel ID. */
+  chatId: string;
+  /** Sender user ID. */
+  userId: string;
+  /** Sender username (if available). */
+  username?: string;
+  /** Message type. */
+  type: 'text' | 'voice' | 'photo';
+  /** Text content (for text messages or transcribed voice). */
+  text?: string;
+  /** Voice metadata. */
+  voice?: { fileId: string; duration: number };
+  /** Photo metadata. */
+  photo?: { fileId: string; caption?: string };
+  /** ISO timestamp. */
+  timestamp: string;
+}
+
+export interface QueuedResponse {
+  /** Original message ID this responds to. */
+  messageId: string;
+  /** Target chat ID. */
+  chatId: string;
+  /** Response text. */
+  text: string;
+  /** ISO timestamp. */
+  timestamp: string;
+}
+
+export interface QueueConfig {
+  /** Base directory for queue (e.g., ~/.{agentId}/queue). */
+  queueDir: string;
+}
+
+// ─── Queue Manager ───────────────────────────────────────────────────
+
+export class MessageQueue {
+  private readonly inboxDir: string;
+  private readonly outboxDir: string;
+
+  constructor(config: QueueConfig) {
+    this.inboxDir = join(config.queueDir, 'inbox');
+    this.outboxDir = join(config.queueDir, 'outbox');
+    mkdirSync(this.inboxDir, { recursive: true });
+    mkdirSync(this.outboxDir, { recursive: true });
+  }
+
+  /**
+   * Enqueue an incoming message to inbox.
+   */
+  enqueue(msg: Omit<QueuedMessage, 'id' | 'timestamp'>): QueuedMessage {
+    const timestamp = new Date().toISOString();
+    const id = `${msg.chatId}-${Date.now()}`;
+    const queued: QueuedMessage = { ...msg, id, timestamp };
+    const filename = `${id}.json`;
+    writeFileSync(join(this.inboxDir, filename), JSON.stringify(queued, null, 2), 'utf-8');
+    return queued;
+  }
+
+  /**
+   * Read all pending inbox messages, sorted by timestamp.
+   */
+  readInbox(): QueuedMessage[] {
+    const files = this.listJsonFiles(this.inboxDir);
+    const messages: QueuedMessage[] = [];
+
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(this.inboxDir, file), 'utf-8');
+        messages.push(JSON.parse(raw) as QueuedMessage);
+      } catch {
+        // Skip corrupt files
+      }
+    }
+
+    return messages.sort(
+      (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+    );
+  }
+
+  /**
+   * Get the number of pending inbox messages.
+   */
+  inboxCount(): number {
+    return this.listJsonFiles(this.inboxDir).length;
+  }
+
+  /**
+   * Remove a message from inbox (after processing).
+   */
+  removeFromInbox(messageId: string): boolean {
+    const filename = `${messageId}.json`;
+    const filepath = join(this.inboxDir, filename);
+    if (!existsSync(filepath)) return false;
+    try {
+      unlinkSync(filepath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Write a response to outbox.
+   */
+  sendResponse(messageId: string, chatId: string, text: string): QueuedResponse {
+    const response: QueuedResponse = {
+      messageId,
+      chatId,
+      text,
+      timestamp: new Date().toISOString(),
+    };
+    const filename = `${chatId}-${Date.now()}.json`;
+    writeFileSync(join(this.outboxDir, filename), JSON.stringify(response, null, 2), 'utf-8');
+    // Remove from inbox
+    this.removeFromInbox(messageId);
+    return response;
+  }
+
+  /**
+   * Read and remove all pending outbox responses.
+   */
+  drainOutbox(): QueuedResponse[] {
+    const files = this.listJsonFiles(this.outboxDir);
+    const responses: QueuedResponse[] = [];
+
+    for (const file of files) {
+      const filepath = join(this.outboxDir, file);
+      try {
+        const raw = readFileSync(filepath, 'utf-8');
+        responses.push(JSON.parse(raw) as QueuedResponse);
+        unlinkSync(filepath);
+      } catch {
+        // Skip corrupt files
+      }
+    }
+
+    return responses.sort(
+      (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+    );
+  }
+
+  /**
+   * Get outbox count.
+   */
+  outboxCount(): number {
+    return this.listJsonFiles(this.outboxDir).length;
+  }
+
+  /**
+   * Format inbox as readable text (for MCP tool output).
+   */
+  formatInbox(): string {
+    const messages = this.readInbox();
+    if (messages.length === 0) return 'No pending messages.';
+
+    return messages
+      .map((m) => {
+        const age = Math.round((Date.now() - new Date(m.timestamp).getTime()) / 1000);
+        const content =
+          m.type === 'text'
+            ? m.text
+            : m.type === 'voice'
+              ? `[Voice: ${m.voice?.duration}s]`
+              : `[Photo: ${m.photo?.caption ?? 'no caption'}]`;
+        return `[${m.id}] ${m.username ?? m.userId} (${age}s ago): ${content}`;
+      })
+      .join('\n');
+  }
+
+  private listJsonFiles(dir: string): string[] {
+    try {
+      return readdirSync(dir)
+        .filter((f) => f.endsWith('.json'))
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+}

package/src/chat/response-chunker.ts

@@ -0,0 +1,200 @@
+/**
+ * Response Chunker — splits long agent responses for chat platforms.
+ *
+ * Two capabilities:
+ * 1. Markdown → HTML conversion (for Telegram-style HTML parse mode)
+ * 2. Smart chunking at natural boundaries (paragraphs, sentences, words)
+ *
+ * Ported from Salvador's response-chunker.ts with improvements:
+ * - Cleaner code block protection (no sentinel characters)
+ * - Supports multiple output formats (HTML, Markdown passthrough, plain)
+ * - Better heading handling
+ */
+
+import type { ChunkConfig, MarkupFormat } from './types.js';
+
+const DEFAULT_MAX_CHUNK_SIZE = 4000;
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Convert Markdown to the target format and split into chunks.
+ */
+export function chunkResponse(text: string, config?: ChunkConfig): string[] {
+  const maxSize = config?.maxChunkSize ?? DEFAULT_MAX_CHUNK_SIZE;
+  const format = config?.format ?? 'html';
+
+  const converted = convertMarkup(text, format);
+
+  if (converted.length <= maxSize) return [converted];
+
+  return splitAtBoundaries(converted, maxSize);
+}
+
+/**
+ * Convert Markdown to the target markup format.
+ */
+export function convertMarkup(text: string, format: MarkupFormat): string {
+  switch (format) {
+    case 'html':
+      return markdownToHtml(text);
+    case 'plain':
+      return markdownToPlain(text);
+    case 'markdown':
+    default:
+      return text;
+  }
+}
+
+// ─── Markdown → HTML ────────────────────────────────────────────────
+
+/**
+ * Convert Markdown to Telegram-compatible HTML.
+ *
+ * Handles: headings, bold, italic, strikethrough, code, links,
+ * blockquotes, lists, and fenced code blocks.
+ */
+export function markdownToHtml(text: string): string {
+  // Protect fenced code blocks first
+  const codeBlocks: string[] = [];
+  let processed = text.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, lang, code) => {
+    const escaped = escapeHtml(code.trimEnd());
+    const langAttr = lang ? ` class="language-${escapeHtml(lang)}"` : '';
+    codeBlocks.push(`<pre><code${langAttr}>${escaped}</code></pre>`);
+    return `<<CODEBLOCK_${codeBlocks.length - 1}>>`;
+  });
+
+  // Inline code
+  processed = processed.replace(/`([^`]+)`/g, (_m, code) => `<code>${escapeHtml(code)}</code>`);
+
+  // Headings → bold
+  processed = processed.replace(/^#{1,6}\s+(.+)$/gm, '<b>$1</b>');
+
+  // Bold + italic
+  processed = processed.replace(/\*\*\*(.+?)\*\*\*/g, '<b><i>$1</i></b>');
+  // Bold
+  processed = processed.replace(/\*\*(.+?)\*\*/g, '<b>$1</b>');
+  // Italic
+  processed = processed.replace(/(?<!\*)\*([^*]+?)\*(?!\*)/g, '<i>$1</i>');
+  // Strikethrough
+  processed = processed.replace(/~~(.+?)~~/g, '<s>$1</s>');
+
+  // Links
+  processed = processed.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+  // Blockquotes
+  processed = processed.replace(/^>\s?(.*)$/gm, '<blockquote>$1</blockquote>');
+  // Merge consecutive blockquotes
+  processed = processed.replace(/<\/blockquote>\n<blockquote>/g, '\n');
+
+  // Unordered lists
+  processed = processed.replace(/^[-*]\s+(.+)$/gm, '• $1');
+  // Ordered lists
+  processed = processed.replace(/^\d+\.\s+(.+)$/gm, '• $1');
+
+  // Horizontal rules
+  processed = processed.replace(/^---+$/gm, '─'.repeat(20));
+
+  // Restore code blocks
+  processed = processed.replace(/<<CODEBLOCK_(\d+)>>/g, (_m, i) => codeBlocks[Number(i)]);
+
+  return processed.trim();
+}
+
+// ─── Markdown → Plain ───────────────────────────────────────────────
+
+function markdownToPlain(text: string): string {
+  let plain = text;
+
+  // Remove fenced code block markers (keep content)
+  plain = plain.replace(/```\w*\n?/g, '');
+
+  // Remove inline formatting
+  plain = plain.replace(/\*\*\*(.+?)\*\*\*/g, '$1');
+  plain = plain.replace(/\*\*(.+?)\*\*/g, '$1');
+  plain = plain.replace(/(?<!\*)\*([^*]+?)\*(?!\*)/g, '$1');
+  plain = plain.replace(/~~(.+?)~~/g, '$1');
+  plain = plain.replace(/`([^`]+)`/g, '$1');
+
+  // Headings → plain text
+  plain = plain.replace(/^#{1,6}\s+/gm, '');
+
+  // Links → text (URL)
+  plain = plain.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1 ($2)');
+
+  // Blockquotes
+  plain = plain.replace(/^>\s?/gm, '');
+
+  // Lists
+  plain = plain.replace(/^[-*]\s+/gm, '• ');
+
+  return plain.trim();
+}
+
+// ─── Chunking ───────────────────────────────────────────────────────
+
+function splitAtBoundaries(text: string, maxSize: number): string[] {
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > maxSize) {
+    const cutPoint = findCutPoint(remaining, maxSize);
+    chunks.push(remaining.slice(0, cutPoint).trimEnd());
+    remaining = remaining.slice(cutPoint).trimStart();
+  }
+
+  if (remaining.length > 0) {
+    chunks.push(remaining.trimEnd());
+  }
+
+  return chunks;
+}
+
+/**
+ * Find the best cut point, prioritizing natural boundaries:
+ * 1. Paragraph break (double newline)
+ * 2. Line break
+ * 3. Sentence boundary (. ! ?)
+ * 4. Word boundary (space)
+ * 5. Hard cut at maxSize
+ */
+function findCutPoint(text: string, maxSize: number): number {
+  const window = text.slice(0, maxSize);
+
+  // Try paragraph break (must be at least 30% into the chunk to be useful)
+  const minUseful = Math.floor(maxSize * 0.3);
+  const paragraphBreak = window.lastIndexOf('\n\n');
+  if (paragraphBreak >= minUseful) return paragraphBreak + 2;
+
+  // Try line break
+  const lineBreak = window.lastIndexOf('\n');
+  if (lineBreak >= minUseful) return lineBreak + 1;
+
+  // Try sentence boundary
+  const sentenceEnd = findLastSentenceEnd(window, minUseful);
+  if (sentenceEnd > 0) return sentenceEnd;
+
+  // Try word boundary
+  const spaceBreak = window.lastIndexOf(' ');
+  if (spaceBreak >= minUseful) return spaceBreak + 1;
+
+  // Hard cut
+  return maxSize;
+}
+
+function findLastSentenceEnd(text: string, minPos: number): number {
+  // Look for ". " or "! " or "? " from the end
+  for (let i = text.length - 1; i >= minPos; i--) {
+    const ch = text[i];
+    if ((ch === '.' || ch === '!' || ch === '?') && i + 1 < text.length && text[i + 1] === ' ') {
+      return i + 2;
+    }
+  }
+  return -1;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}