@soleri/core 2.9.0 → 2.11.0

package/src/chat/file-handler.ts

@@ -0,0 +1,230 @@
+/**
+ * File Handler — intent detection and multimodal message building for chat transports.
+ *
+ * Provides transport-agnostic utilities for handling files sent by users:
+ * - Intent detection: should this file be viewed (vision), read as text, or ingested?
+ * - Multimodal message building for Anthropic API (ImageBlock, DocumentBlock)
+ * - Temp file management
+ *
+ * The actual file download is transport-specific (Telegram, Discord, etc.)
+ * and belongs in forge templates.
+ */
+
+import { mkdirSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+
+// ─── Constants ────────────────────────────────────────────────────────
+
+/** Maximum file size in bytes (Telegram limit). */
+export const MAX_FILE_SIZE = 20 * 1024 * 1024; // 20MB
+
+/** File extensions treated as readable text. */
+export const TEXT_EXTENSIONS = new Set([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.py',
+  '.rb',
+  '.rs',
+  '.go',
+  '.java',
+  '.kt',
+  '.swift',
+  '.c',
+  '.cpp',
+  '.h',
+  '.cs',
+  '.php',
+  '.sh',
+  '.bash',
+  '.zsh',
+  '.fish',
+  '.md',
+  '.txt',
+  '.json',
+  '.yaml',
+  '.yml',
+  '.toml',
+  '.xml',
+  '.html',
+  '.css',
+  '.scss',
+  '.sql',
+  '.graphql',
+  '.prisma',
+  '.env',
+  '.gitignore',
+  '.dockerfile',
+  '.csv',
+  '.log',
+]);
+
+/** MIME types supported for vision (ImageBlock). */
+export const IMAGE_MIME_TYPES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
+
+/** Keywords that indicate the user wants to ingest/learn from the file. */
+export const INTAKE_KEYWORDS = [
+  'learn',
+  'ingest',
+  'absorb',
+  'study',
+  'memorize',
+  'remember',
+  'read this',
+  'save this',
+  'store this',
+  'add to vault',
+  'add to knowledge',
+];
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export type FileIntent = 'vision' | 'text' | 'intake';
+
+export interface FileInfo {
+  /** Original filename. */
+  name: string;
+  /** MIME type. */
+  mimeType: string;
+  /** File size in bytes. */
+  size: number;
+  /** File content as Buffer. */
+  data: Buffer;
+}
+
+export interface MultimodalContent {
+  type: 'image' | 'document' | 'text';
+  /** For image: base64 data. For document: base64 data. For text: the text content. */
+  content: string;
+  /** MIME type (for image/document). */
+  mimeType?: string;
+  /** Source filename. */
+  filename?: string;
+}
+
+// ─── Intent Detection ─────────────────────────────────────────────────
+
+/**
+ * Detect what the user wants to do with a file based on its type and
+ * any accompanying text message.
+ */
+export function detectFileIntent(
+  filename: string,
+  mimeType: string,
+  userText?: string,
+): FileIntent {
+  const ext = extname(filename).toLowerCase();
+  const textLower = userText?.toLowerCase() ?? '';
+
+  // Check for intake keywords first
+  if (userText && INTAKE_KEYWORDS.some((kw) => textLower.includes(kw))) {
+    return 'intake';
+  }
+
+  // Text files → read as text
+  if (TEXT_EXTENSIONS.has(ext)) {
+    return 'text';
+  }
+
+  // Images → vision
+  if (IMAGE_MIME_TYPES.has(mimeType) || mimeType.startsWith('image/')) {
+    return 'vision';
+  }
+
+  // PDFs → vision (DocumentBlock)
+  if (mimeType === 'application/pdf' || ext === '.pdf') {
+    return 'vision';
+  }
+
+  // Default: try vision
+  return 'vision';
+}
+
+// ─── Multimodal Message Building ──────────────────────────────────────
+
+/**
+ * Build multimodal content from a file for the Anthropic API.
+ */
+export function buildMultimodalContent(file: FileInfo, intent: FileIntent): MultimodalContent {
+  const ext = extname(file.name).toLowerCase();
+
+  if (intent === 'text' || TEXT_EXTENSIONS.has(ext)) {
+    return {
+      type: 'text',
+      content: file.data.toString('utf-8'),
+      filename: file.name,
+    };
+  }
+
+  if (IMAGE_MIME_TYPES.has(file.mimeType)) {
+    return {
+      type: 'image',
+      content: file.data.toString('base64'),
+      mimeType: file.mimeType,
+      filename: file.name,
+    };
+  }
+
+  // PDF and other documents
+  return {
+    type: 'document',
+    content: file.data.toString('base64'),
+    mimeType: file.mimeType,
+    filename: file.name,
+  };
+}
+
+// ─── Temp File Management ─────────────────────────────────────────────
+
+/**
+ * Save a file to a temp directory with timestamp prefix.
+ * Returns the full path.
+ */
+export function saveTempFile(uploadDir: string, filename: string, data: Buffer): string {
+  mkdirSync(uploadDir, { recursive: true });
+  const safeName = filename.replace(/[^\w.-]/g, '_');
+  const path = join(uploadDir, `${Date.now()}-${safeName}`);
+  writeFileSync(path, data);
+  return path;
+}
+
+/**
+ * Clean up temp files older than maxAgeMs.
+ */
+export function cleanupTempFiles(uploadDir: string, maxAgeMs: number = 3_600_000): number {
+  let removed = 0;
+  try {
+    const cutoff = Date.now() - maxAgeMs;
+    const files = readdirSync(uploadDir);
+    for (const file of files) {
+      const filePath = join(uploadDir, file);
+      try {
+        const stat = statSync(filePath);
+        if (stat.mtimeMs < cutoff) {
+          rmSync(filePath);
+          removed++;
+        }
+      } catch {
+        // Skip files we can't stat
+      }
+    }
+  } catch {
+    // Directory doesn't exist or can't be read
+  }
+  return removed;
+}
+
+/**
+ * Strip base64 data from multimodal content for session persistence.
+ * Replaces binary content with a size placeholder to prevent session bloat.
+ */
+export function sanitizeForPersistence(content: MultimodalContent): MultimodalContent {
+  if (content.type === 'text') return content;
+
+  const sizeKb = Math.round(Buffer.byteLength(content.content, 'base64') / 1024);
+  return {
+    ...content,
+    content: `[${content.type}: ${content.filename ?? 'file'}, ${sizeKb}KB]`,
+  };
+}

package/src/chat/fragment-buffer.ts

@@ -0,0 +1,160 @@
+/**
+ * Fragment Buffer — merges split messages from chat platforms.
+ *
+ * Telegram, Discord, and other platforms split long pastes into multiple
+ * messages (e.g. Telegram's 4096 char limit). This buffer detects near-limit
+ * messages and waits briefly for follow-up parts before flushing as one unit.
+ *
+ * Ported from Salvador's handler-messages.ts with improvements:
+ * - Transport-agnostic (works for any chat platform)
+ * - Callback-based flush (no transport dependency)
+ * - Configurable thresholds
+ */
+
+import type { Fragment, FragmentBufferConfig } from './types.js';
+
+const DEFAULT_START_THRESHOLD = 4000;
+const DEFAULT_MAX_GAP_MS = 1500;
+const DEFAULT_MAX_PARTS = 12;
+const DEFAULT_MAX_TOTAL_BYTES = 50_000;
+
+interface PendingBuffer {
+  key: string;
+  fragments: Fragment[];
+  totalBytes: number;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class FragmentBuffer {
+  private buffers = new Map<string, PendingBuffer>();
+  private config: Required<FragmentBufferConfig>;
+  private onFlush: (key: string, merged: string) => void;
+
+  constructor(
+    config: FragmentBufferConfig | undefined,
+    onFlush: (key: string, merged: string) => void,
+  ) {
+    this.config = {
+      startThreshold: config?.startThreshold ?? DEFAULT_START_THRESHOLD,
+      maxGapMs: config?.maxGapMs ?? DEFAULT_MAX_GAP_MS,
+      maxParts: config?.maxParts ?? DEFAULT_MAX_PARTS,
+      maxTotalBytes: config?.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES,
+    };
+    this.onFlush = onFlush;
+  }
+
+  /**
+   * Receive a message. Returns true if the message was buffered (caller should wait),
+   * false if the message should be processed immediately.
+   */
+  receive(key: string, fragment: Fragment): boolean {
+    const existing = this.buffers.get(key);
+
+    if (existing) {
+      // Append to existing buffer
+      return this.appendToBuffer(existing, fragment);
+    }
+
+    // Check if this message is long enough to start buffering
+    if (fragment.text.length >= this.config.startThreshold) {
+      this.startBuffer(key, fragment);
+      return true;
+    }
+
+    // Short message — process immediately
+    return false;
+  }
+
+  /**
+   * Force-flush a specific buffer. Returns the merged text or null if no buffer.
+   */
+  flush(key: string): string | null {
+    const buffer = this.buffers.get(key);
+    if (!buffer) return null;
+
+    clearTimeout(buffer.timer);
+    const merged = this.mergeFragments(buffer.fragments);
+    this.buffers.delete(key);
+    return merged;
+  }
+
+  /**
+   * Force-flush all pending buffers.
+   */
+  flushAll(): void {
+    for (const [key, buffer] of this.buffers) {
+      clearTimeout(buffer.timer);
+      const merged = this.mergeFragments(buffer.fragments);
+      this.buffers.delete(key);
+      this.onFlush(key, merged);
+    }
+  }
+
+  /**
+   * Number of keys with pending fragments.
+   */
+  get pendingCount(): number {
+    return this.buffers.size;
+  }
+
+  /**
+   * Check if a key has pending fragments.
+   */
+  hasPending(key: string): boolean {
+    return this.buffers.has(key);
+  }
+
+  /**
+   * Close the buffer — flush all and clean up timers.
+   */
+  close(): void {
+    for (const buffer of this.buffers.values()) {
+      clearTimeout(buffer.timer);
+    }
+    this.buffers.clear();
+  }
+
+  // ─── Private ───────────────────────────────────────────────────
+
+  private startBuffer(key: string, fragment: Fragment): void {
+    const timer = setTimeout(() => this.autoFlush(key), this.config.maxGapMs);
+    this.buffers.set(key, {
+      key,
+      fragments: [fragment],
+      totalBytes: fragment.text.length,
+      timer,
+    });
+  }
+
+  private appendToBuffer(buffer: PendingBuffer, fragment: Fragment): boolean {
+    const newTotal = buffer.totalBytes + fragment.text.length;
+
+    // Force-flush if limits exceeded
+    if (buffer.fragments.length >= this.config.maxParts || newTotal > this.config.maxTotalBytes) {
+      this.autoFlush(buffer.key);
+      // The new fragment starts fresh — don't buffer it
+      return false;
+    }
+
+    // Append and reset timer
+    clearTimeout(buffer.timer);
+    buffer.fragments.push(fragment);
+    buffer.totalBytes = newTotal;
+    buffer.timer = setTimeout(() => this.autoFlush(buffer.key), this.config.maxGapMs);
+    return true;
+  }
+
+  private autoFlush(key: string): void {
+    const buffer = this.buffers.get(key);
+    if (!buffer) return;
+
+    clearTimeout(buffer.timer);
+    const merged = this.mergeFragments(buffer.fragments);
+    this.buffers.delete(key);
+    this.onFlush(key, merged);
+  }
+
+  private mergeFragments(fragments: Fragment[]): string {
+    return fragments.map((f) => f.text).join('\n');
+  }
+}

package/src/chat/index.ts

@@ -0,0 +1,72 @@
+export { ChatSessionManager } from './chat-session.js';
+export { FragmentBuffer } from './fragment-buffer.js';
+export { ChatAuthManager } from './auth-manager.js';
+export { TaskCancellationManager } from './cancellation.js';
+export { SelfUpdateManager, RESTART_EXIT_CODE } from './self-update.js';
+export { NotificationEngine } from './notifications.js';
+export {
+  detectFileIntent,
+  buildMultimodalContent,
+  saveTempFile,
+  cleanupTempFiles,
+  sanitizeForPersistence,
+  MAX_FILE_SIZE,
+  TEXT_EXTENSIONS,
+  IMAGE_MIME_TYPES,
+  INTAKE_KEYWORDS,
+} from './file-handler.js';
+export { transcribeAudio, synthesizeSpeech } from './voice.js';
+export { MessageQueue } from './queue.js';
+export { BrowserSessionManager } from './browser-session.js';
+export { chunkResponse, convertMarkup, markdownToHtml } from './response-chunker.js';
+export { runAgentLoop } from './agent-loop.js';
+export { McpToolBridge } from './mcp-bridge.js';
+export {
+  createOutputCompressor,
+  registerCompressor,
+  clearCompressors,
+} from './output-compressor.js';
+
+export type {
+  ChatRole,
+  ChatMessage,
+  ChatSession,
+  ChatSessionConfig,
+  Fragment,
+  FragmentBufferConfig,
+  MarkupFormat,
+  ChunkConfig,
+  ChatAuthConfig,
+  AuthRecord,
+  AuthState,
+  ChatManagerConfig,
+  ChatManagerStatus,
+} from './types.js';
+
+export type {
+  AgentTool,
+  ToolResult,
+  ToolExecutor,
+  AgentLoopConfig,
+  AgentCallbacks,
+  AgentLoopResult,
+  McpToolRegistration,
+  OutputCompressor,
+} from './agent-loop-types.js';
+
+export type { CancellationInfo } from './cancellation.js';
+export type { RestartContext, RestartResult } from './self-update.js';
+export type {
+  NotificationCheck,
+  NotificationEngineConfig,
+  NotificationStats,
+} from './notifications.js';
+export type { FileIntent, FileInfo, MultimodalContent } from './file-handler.js';
+export type { VoiceConfig, TranscriptionResult, SpeechResult } from './voice.js';
+export type { QueuedMessage, QueuedResponse, QueueConfig } from './queue.js';
+export type {
+  BrowserSessionConfig,
+  BrowserSession,
+  BrowserTool,
+  BrowserToolResult,
+} from './browser-session.js';

package/src/chat/mcp-bridge.ts

@@ -0,0 +1,135 @@
+/**
+ * MCP Tool Bridge — intercepts MCP tool registrations and executes locally.
+ *
+ * Ported from Salvador's mcp-bridge.ts with improvements:
+ * - Simpler API (no Zod dependency — accepts JSON Schema directly)
+ * - Optional allowlist for tool filtering
+ * - Generic output compression hook
+ *
+ * Used by Telegram (and other chat transports) to bridge the agent's MCP tools
+ * into the agent loop without network round-trips.
+ */
+
+import type {
+  AgentTool,
+  ToolResult,
+  McpToolRegistration,
+  OutputCompressor,
+} from './agent-loop-types.js';
+
+const DEFAULT_MAX_OUTPUT = 10_000; // 10KB
+
+export class McpToolBridge {
+  private tools = new Map<string, McpToolRegistration>();
+  private allowlist: Set<string> | null;
+  private compressor: OutputCompressor | null;
+  private maxOutput: number;
+
+  constructor(options?: {
+    allowlist?: string[];
+    compressor?: OutputCompressor;
+    maxOutput?: number;
+  }) {
+    this.allowlist = options?.allowlist ? new Set(options.allowlist) : null;
+    this.compressor = options?.compressor ?? null;
+    this.maxOutput = options?.maxOutput ?? DEFAULT_MAX_OUTPUT;
+  }
+
+  /**
+   * Register a tool. If an allowlist is set, only allowed tools are registered.
+   */
+  register(tool: McpToolRegistration): void {
+    if (this.allowlist && !this.allowlist.has(tool.name)) return;
+    this.tools.set(tool.name, tool);
+  }
+
+  /**
+   * Register multiple tools at once.
+   */
+  registerAll(tools: McpToolRegistration[]): void {
+    for (const tool of tools) {
+      this.register(tool);
+    }
+  }
+
+  /**
+   * Check if a tool is registered.
+   */
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /**
+   * Get registered tools as AgentTool array (for the agent loop).
+   */
+  getTools(): AgentTool[] {
+    return [...this.tools.values()].map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    }));
+  }
+
+  /**
+   * Execute a tool by name.
+   */
+  async execute(name: string, input: Record<string, unknown>): Promise<ToolResult> {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      return {
+        output: `Unknown tool: ${name}`,
+        isError: true,
+      };
+    }
+
+    try {
+      const rawResult = await tool.handler(input);
+      let output = typeof rawResult === 'string' ? rawResult : JSON.stringify(rawResult);
+
+      // Apply compression if available
+      if (this.compressor) {
+        output = this.compressor(name, output, this.maxOutput);
+      }
+
+      // Truncate if still too long
+      if (output.length > this.maxOutput) {
+        output = output.slice(0, this.maxOutput) + `\n... (truncated at ${this.maxOutput} chars)`;
+      }
+
+      return { output, isError: false };
+    } catch (error) {
+      return {
+        output: `Tool error: ${error instanceof Error ? error.message : String(error)}`,
+        isError: true,
+      };
+    }
+  }
+
+  /**
+   * Create a ToolExecutor function for use with the agent loop.
+   */
+  createExecutor(): (name: string, input: Record<string, unknown>) => Promise<ToolResult> {
+    return (name, input) => this.execute(name, input);
+  }
+
+  /**
+   * Number of registered tools.
+   */
+  get size(): number {
+    return this.tools.size;
+  }
+
+  /**
+   * List registered tool names.
+   */
+  listTools(): string[] {
+    return [...this.tools.keys()];
+  }
+
+  /**
+   * Clear all registered tools.
+   */
+  clear(): void {
+    this.tools.clear();
+  }
+}