@soleri/core 2.9.0 → 2.11.0

package/src/chat/agent-loop-types.ts

@@ -0,0 +1,99 @@
+/**
+ * Agent Loop Types — interfaces for the conversational agent execution engine.
+ *
+ * Transport-agnostic: the agent loop doesn't know about Telegram, Discord, etc.
+ * It takes messages and tools, calls the LLM, dispatches tool calls, and returns.
+ */
+
+import type { ChatMessage } from './types.js';
+
+// ─── Tool Types ──────────────────────────────────────────────────────
+
+export interface AgentTool {
+  /** Tool name (unique identifier). */
+  name: string;
+  /** Human-readable description for the LLM. */
+  description: string;
+  /** JSON Schema for tool input parameters. */
+  inputSchema: Record<string, unknown>;
+}
+
+export interface ToolResult {
+  /** Output text (may be truncated). */
+  output: string;
+  /** Whether the tool execution errored. */
+  isError: boolean;
+  /** Optional base64-encoded image (e.g. screenshots). */
+  image?: { base64: string; mimeType: string };
+}
+
+export type ToolExecutor = (
+  toolName: string,
+  input: Record<string, unknown>,
+) => Promise<ToolResult>;
+
+// ─── Agent Loop Config ──────────────────────────────────────────────
+
+export interface AgentLoopConfig {
+  /** Anthropic API key. */
+  apiKey: string;
+  /** Model to use. Default: 'claude-sonnet-4-20250514'. */
+  model?: string;
+  /** System prompt. */
+  systemPrompt: string;
+  /** Available tools. */
+  tools: AgentTool[];
+  /** Tool executor function — routes tool calls to handlers. */
+  executor: ToolExecutor;
+  /** Max iterations (LLM calls) before stopping. Default: 200. */
+  maxIterations?: number;
+  /** Max output tokens per LLM call. Default: 16384. */
+  maxTokens?: number;
+  /** Optional AbortSignal for cancellation. */
+  signal?: AbortSignal;
+  /** Base URL for Anthropic API. Default: 'https://api.anthropic.com'. */
+  baseUrl?: string;
+}
+
+// ─── Callbacks ──────────────────────────────────────────────────────
+
+export interface AgentCallbacks {
+  /** Called when the LLM invokes a tool. */
+  onToolUse?: (toolName: string, input: Record<string, unknown>) => void;
+  /** Called when a tool returns a result. */
+  onToolResult?: (toolName: string, result: ToolResult, durationMs: number) => void;
+  /** Called on each iteration (LLM call). */
+  onIteration?: (iteration: number) => void;
+  /** Called when an error occurs (non-fatal — loop may continue). */
+  onError?: (error: Error, context: string) => void;
+}
+
+// ─── Agent Loop Result ──────────────────────────────────────────────
+
+export interface AgentLoopResult {
+  /** Final text response (concatenated from all text blocks). */
+  text: string;
+  /** Number of LLM iterations. */
+  iterations: number;
+  /** Total tool calls made. */
+  toolCalls: number;
+  /** New messages to append to session (assistant + tool_result pairs). */
+  newMessages: ChatMessage[];
+  /** Stop reason: 'end_turn', 'max_iterations', 'cancelled'. */
+  stopReason: 'end_turn' | 'max_iterations' | 'cancelled';
+  /** Usage stats. */
+  usage: { inputTokens: number; outputTokens: number };
+}
+
+// ─── MCP Bridge Types ───────────────────────────────────────────────
+
+export interface McpToolRegistration {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (input: Record<string, unknown>) => Promise<unknown>;
+}
+
+// ─── Output Compressor ──────────────────────────────────────────────
+
+export type OutputCompressor = (toolName: string, output: string, maxLength?: number) => string;

package/src/chat/agent-loop.ts

@@ -0,0 +1,357 @@
+/**
+ * Agent Loop — conversational agent execution engine.
+ *
+ * Pure computation: takes messages + tools, calls LLM, dispatches tool calls, returns result.
+ * Transport-specific concerns (typing indicators, progress messages) live in callbacks.
+ *
+ * Ported from Salvador's agent-loop.ts with improvements:
+ * - Transport-agnostic (no Grammy dependency)
+ * - AbortSignal support for clean cancellation
+ * - Pure HTTP (no Anthropic SDK dependency — zero deps)
+ * - Callbacks for all lifecycle events
+ */
+
+import type { AgentLoopConfig, AgentLoopResult, AgentCallbacks } from './agent-loop-types.js';
+import type { ChatMessage } from './types.js';
+
+const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+const DEFAULT_MAX_ITERATIONS = 200;
+const DEFAULT_MAX_TOKENS = 16384;
+const DEFAULT_BASE_URL = 'https://api.anthropic.com';
+const API_VERSION = '2023-06-01';
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Run the agent loop — iteratively call LLM and dispatch tools until done.
+ */
+export async function runAgentLoop(
+  messages: ChatMessage[],
+  config: AgentLoopConfig,
+  callbacks?: AgentCallbacks,
+): Promise<AgentLoopResult> {
+  const model = config.model ?? DEFAULT_MODEL;
+  const maxIterations = config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+  const maxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+
+  // Convert ChatMessages to Anthropic format
+  const apiMessages = sanitizeMessages(messages);
+  const newMessages: ChatMessage[] = [];
+
+  let iterations = 0;
+  let toolCalls = 0;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  const textParts: string[] = [];
+
+  while (iterations < maxIterations) {
+    // Check for cancellation
+    if (config.signal?.aborted) {
+      return {
+        text: textParts.join('\n'),
+        iterations,
+        toolCalls,
+        newMessages,
+        stopReason: 'cancelled',
+        usage: { inputTokens: totalInputTokens, outputTokens: totalOutputTokens },
+      };
+    }
+
+    iterations++;
+    callbacks?.onIteration?.(iterations);
+
+    // Call the Anthropic API
+    let response: AnthropicResponse;
+    try {
+      response = await callAnthropic({
+        baseUrl,
+        apiKey: config.apiKey,
+        model,
+        systemPrompt: config.systemPrompt,
+        messages: apiMessages,
+        tools: config.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: t.inputSchema,
+        })),
+        maxTokens,
+        signal: config.signal,
+      });
+    } catch (error) {
+      if (config.signal?.aborted) {
+        return {
+          text: textParts.join('\n'),
+          iterations,
+          toolCalls,
+          newMessages,
+          stopReason: 'cancelled',
+          usage: { inputTokens: totalInputTokens, outputTokens: totalOutputTokens },
+        };
+      }
+      callbacks?.onError?.(error instanceof Error ? error : new Error(String(error)), 'api_call');
+      throw error;
+    }
+
+    totalInputTokens += response.usage?.input_tokens ?? 0;
+    totalOutputTokens += response.usage?.output_tokens ?? 0;
+
+    // Process content blocks
+    const assistantContent = response.content;
+    const assistantBlocks: unknown[] = [];
+    const toolUseBlocks: ToolUseBlock[] = [];
+
+    for (const block of assistantContent) {
+      assistantBlocks.push(block);
+
+      if (block.type === 'text') {
+        textParts.push(block.text);
+      } else if (block.type === 'tool_use') {
+        toolUseBlocks.push(block);
+      }
+    }
+
+    // Record assistant message
+    const assistantMsg: ChatMessage = {
+      role: 'assistant',
+      content: assistantContent
+        .filter((b): b is TextBlock => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n'),
+      blocks: assistantBlocks,
+      timestamp: Date.now(),
+    };
+    apiMessages.push({ role: 'assistant', content: assistantContent });
+    newMessages.push(assistantMsg);
+
+    // If no tool calls, we're done
+    if (toolUseBlocks.length === 0 || response.stop_reason === 'end_turn') {
+      if (toolUseBlocks.length === 0) {
+        return {
+          text: textParts.join('\n'),
+          iterations,
+          toolCalls,
+          newMessages,
+          stopReason: 'end_turn',
+          usage: { inputTokens: totalInputTokens, outputTokens: totalOutputTokens },
+        };
+      }
+    }
+
+    // Execute tool calls
+    const toolResults: ApiToolResult[] = [];
+    for (const toolUse of toolUseBlocks) {
+      if (config.signal?.aborted) {
+        return {
+          text: textParts.join('\n'),
+          iterations,
+          toolCalls,
+          newMessages,
+          stopReason: 'cancelled',
+          usage: { inputTokens: totalInputTokens, outputTokens: totalOutputTokens },
+        };
+      }
+
+      toolCalls++;
+      callbacks?.onToolUse?.(toolUse.name, toolUse.input as Record<string, unknown>);
+
+      const startTime = Date.now();
+      let result;
+      try {
+        result = await config.executor(toolUse.name, toolUse.input as Record<string, unknown>);
+      } catch (error) {
+        result = {
+          output: `Tool execution error: ${error instanceof Error ? error.message : String(error)}`,
+          isError: true,
+        };
+        callbacks?.onError?.(
+          error instanceof Error ? error : new Error(String(error)),
+          `tool:${toolUse.name}`,
+        );
+      }
+      const durationMs = Date.now() - startTime;
+      callbacks?.onToolResult?.(toolUse.name, result, durationMs);
+
+      // Build tool_result content
+      const resultContent: ApiContent[] = [{ type: 'text', text: result.output }];
+      if (result.image) {
+        resultContent.push({
+          type: 'image',
+          source: {
+            type: 'base64',
+            media_type: result.image.mimeType,
+            data: result.image.base64,
+          },
+        } as ApiContent);
+      }
+
+      toolResults.push({
+        type: 'tool_result',
+        tool_use_id: toolUse.id,
+        content: resultContent,
+        is_error: result.isError,
+      });
+    }
+
+    // Append tool results
+    apiMessages.push({ role: 'user', content: toolResults as unknown as ApiContent[] });
+    for (const tr of toolResults) {
+      newMessages.push({
+        role: 'tool',
+        content:
+          tr.content
+            .filter((c): c is TextBlock => (c as TextBlock).type === 'text')
+            .map((c) => (c as TextBlock).text)
+            .join('\n') || '',
+        blocks: [tr],
+        timestamp: Date.now(),
+      });
+    }
+  }
+
+  // Max iterations reached
+  return {
+    text: textParts.join('\n'),
+    iterations,
+    toolCalls,
+    newMessages,
+    stopReason: 'max_iterations',
+    usage: { inputTokens: totalInputTokens, outputTokens: totalOutputTokens },
+  };
+}
+
+// ─── Message Sanitization ───────────────────────────────────────────
+
+/**
+ * Sanitize messages for the Anthropic API:
+ * - Ensure first message is from 'user'
+ * - Remove orphaned tool_result blocks
+ */
+function sanitizeMessages(messages: ChatMessage[]): ApiMessage[] {
+  const apiMessages: ApiMessage[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === 'tool') {
+      // Tool results are embedded in user messages — skip standalone ones
+      // They'll be re-created during the loop
+      continue;
+    }
+
+    if (msg.blocks && msg.blocks.length > 0) {
+      apiMessages.push({
+        role: msg.role === 'assistant' ? 'assistant' : 'user',
+        content: msg.blocks as ApiContent[],
+      });
+    } else {
+      apiMessages.push({
+        role: msg.role === 'assistant' ? 'assistant' : 'user',
+        content: msg.content,
+      });
+    }
+  }
+
+  // Ensure first message is from user
+  while (apiMessages.length > 0 && apiMessages[0].role !== 'user') {
+    apiMessages.shift();
+  }
+
+  return apiMessages;
+}
+
+// ─── Anthropic API Call ─────────────────────────────────────────────
+
+interface AnthropicCallParams {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  systemPrompt: string;
+  messages: ApiMessage[];
+  tools: ApiTool[];
+  maxTokens: number;
+  signal?: AbortSignal;
+}
+
+async function callAnthropic(params: AnthropicCallParams): Promise<AnthropicResponse> {
+  const url = `${params.baseUrl}/v1/messages`;
+
+  const body = {
+    model: params.model,
+    max_tokens: params.maxTokens,
+    system: params.systemPrompt,
+    messages: params.messages,
+    ...(params.tools.length > 0 ? { tools: params.tools } : {}),
+  };
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': params.apiKey,
+      'anthropic-version': API_VERSION,
+    },
+    body: JSON.stringify(body),
+    signal: params.signal,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => 'Unknown error');
+    const error = new Error(`Anthropic API error ${response.status}: ${errorText}`);
+    (error as ApiError).status = response.status;
+    (error as ApiError).retryAfter = parseRetryAfter(response.headers);
+    throw error;
+  }
+
+  return (await response.json()) as AnthropicResponse;
+}
+
+function parseRetryAfter(headers: Headers): number | undefined {
+  const retryAfter = headers.get('retry-after');
+  if (!retryAfter) return undefined;
+  const seconds = Number(retryAfter);
+  return Number.isFinite(seconds) ? seconds * 1000 : undefined;
+}
+
+// ─── Anthropic API Types (minimal) ─────────────────────────────────
+
+interface ApiError extends Error {
+  status: number;
+  retryAfter?: number;
+}
+
+interface TextBlock {
+  type: 'text';
+  text: string;
+}
+
+interface ToolUseBlock {
+  type: 'tool_use';
+  id: string;
+  name: string;
+  input: unknown;
+}
+
+type ApiContent = TextBlock | ToolUseBlock | Record<string, unknown>;
+
+interface ApiMessage {
+  role: 'user' | 'assistant';
+  content: string | ApiContent[];
+}
+
+interface ApiTool {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+interface ApiToolResult {
+  type: 'tool_result';
+  tool_use_id: string;
+  content: ApiContent[];
+  is_error: boolean;
+}
+
+interface AnthropicResponse {
+  content: (TextBlock | ToolUseBlock)[];
+  stop_reason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence';
+  usage?: { input_tokens: number; output_tokens: number };
+}

package/src/chat/auth-manager.ts

@@ -0,0 +1,171 @@
+/**
+ * Chat Auth Manager — passphrase + allowlist authentication for chat transports.
+ *
+ * Ported from Salvador's bot.ts auth with improvements:
+ * - Configurable passphrase (not hardcoded "Hola Amigo!")
+ * - Rate limiting on failed attempts (lockout after N failures)
+ * - Allowlist support (optional user ID restriction)
+ * - Persistence to disk (survives restarts)
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { ChatAuthConfig, AuthRecord } from './types.js';
+
+const DEFAULT_MAX_FAILED_ATTEMPTS = 5;
+const DEFAULT_LOCKOUT_MS = 300_000; // 5 minutes
+
+interface PersistedAuthState {
+  authenticated: AuthRecord[];
+}
+
+export class ChatAuthManager {
+  private config: Required<ChatAuthConfig>;
+  private authenticated = new Map<string, number>(); // userId → timestamp
+  private failedAttempts = new Map<string, { count: number; lastAttempt: number }>();
+
+  constructor(config: ChatAuthConfig) {
+    this.config = {
+      storagePath: config.storagePath,
+      passphrase: config.passphrase ?? '',
+      allowedUsers: config.allowedUsers ?? [],
+      maxFailedAttempts: config.maxFailedAttempts ?? DEFAULT_MAX_FAILED_ATTEMPTS,
+      lockoutMs: config.lockoutMs ?? DEFAULT_LOCKOUT_MS,
+    };
+
+    this.loadFromDisk();
+  }
+
+  /**
+   * Whether authentication is enabled (passphrase is set).
+   */
+  get enabled(): boolean {
+    return this.config.passphrase.length > 0;
+  }
+
+  /**
+   * Check if a user is authenticated.
+   */
+  isAuthenticated(userId: string | number): boolean {
+    if (!this.enabled) return true;
+    const key = String(userId);
+
+    // Check allowlist first (if configured)
+    if (this.config.allowedUsers.length > 0) {
+      const allowed = this.config.allowedUsers.some((u) => String(u) === key);
+      if (!allowed) return false;
+    }
+
+    return this.authenticated.has(key);
+  }
+
+  /**
+   * Attempt authentication with a passphrase.
+   * Returns true if successful, false otherwise.
+   */
+  authenticate(userId: string | number, passphrase: string): boolean {
+    const key = String(userId);
+
+    // Check allowlist
+    if (this.config.allowedUsers.length > 0) {
+      const allowed = this.config.allowedUsers.some((u) => String(u) === key);
+      if (!allowed) return false;
+    }
+
+    // Check lockout
+    if (this.isLockedOut(key)) return false;
+
+    // Verify passphrase
+    if (passphrase === this.config.passphrase) {
+      this.authenticated.set(key, Date.now());
+      this.failedAttempts.delete(key);
+      this.persistToDisk();
+      return true;
+    }
+
+    // Record failed attempt
+    this.recordFailedAttempt(key);
+    return false;
+  }
+
+  /**
+   * Revoke authentication for a user.
+   */
+  revoke(userId: string | number): void {
+    this.authenticated.delete(String(userId));
+    this.persistToDisk();
+  }
+
+  /**
+   * Check if a user is temporarily locked out.
+   */
+  isLockedOut(userId: string | number): boolean {
+    const key = String(userId);
+    const record = this.failedAttempts.get(key);
+    if (!record) return false;
+
+    if (record.count >= this.config.maxFailedAttempts) {
+      const elapsed = Date.now() - record.lastAttempt;
+      if (elapsed < this.config.lockoutMs) return true;
+      // Lockout expired — reset
+      this.failedAttempts.delete(key);
+    }
+
+    return false;
+  }
+
+  /**
+   * Number of authenticated users.
+   */
+  get authenticatedCount(): number {
+    return this.authenticated.size;
+  }
+
+  /**
+   * List authenticated user IDs.
+   */
+  listAuthenticated(): (string | number)[] {
+    return [...this.authenticated.keys()];
+  }
+
+  // ─── Private ───────────────────────────────────────────────────
+
+  private recordFailedAttempt(key: string): void {
+    const existing = this.failedAttempts.get(key);
+    if (existing) {
+      existing.count++;
+      existing.lastAttempt = Date.now();
+    } else {
+      this.failedAttempts.set(key, { count: 1, lastAttempt: Date.now() });
+    }
+  }
+
+  private persistToDisk(): void {
+    try {
+      mkdirSync(dirname(this.config.storagePath), { recursive: true });
+      const state: PersistedAuthState = {
+        authenticated: [...this.authenticated.entries()].map(([userId, ts]) => ({
+          userId,
+          authenticatedAt: ts,
+        })),
+      };
+      writeFileSync(this.config.storagePath, JSON.stringify(state), 'utf-8');
+    } catch {
+      // Persistence failure is non-critical
+    }
+  }
+
+  private loadFromDisk(): void {
+    if (!existsSync(this.config.storagePath)) return;
+
+    try {
+      const data = readFileSync(this.config.storagePath, 'utf-8');
+      const state = JSON.parse(data) as PersistedAuthState;
+      for (const record of state.authenticated) {
+        this.authenticated.set(String(record.userId), record.authenticatedAt);
+      }
+    } catch {
+      // Load failure is non-critical — start fresh
+    }
+  }
+}