teleton-agent

Implements a 5-iteration maximum agentic loop via AgentRuntime.processMessage() that accepts user messages, routes them through an LLM provider (15+ supported via @mariozechner/pi-ai), parses tool-call responses, executes registered tools with argument validation, and returns final responses. Uses a schema-based function registry where each tool declares input/output types and scopes, enabling the LLM to autonomously decide which of 125+ built-in tools to invoke based on user intent and conversation context.

Implements a dual-index memory system using SQLite with sqlite-vec extension for semantic similarity search (cosine distance on embeddings) and FTS5 for full-text BM25 ranking, fused via Reciprocal Rank Fusion (RRF). Automatically compacts old messages via CompactionManager, which summarizes conversation segments using the LLM and replaces them with condensed entries, maintaining a bounded context window while preserving semantic information. Supports configurable embedding providers (OpenAI, Ollama, local) and stores all data locally in a single SQLite file.

Manages Telegram session persistence via session.json (encrypted) or phone number + 2FA, with automatic reconnection on network failures. Implements exponential backoff for reconnection attempts and state recovery to resume message processing after interruptions. The SessionStore class handles session serialization and encryption, and the TelegramBridge manages connection lifecycle and event routing.

Abstracts LLM provider differences via @mariozechner/pi-ai, supporting 15+ providers (OpenAI, Anthropic, Ollama, Groq, Together, Mistral, etc.) and 70+ models. The LLM provider is configured in config.yaml and can be switched at runtime without code changes. Implements provider-agnostic message formatting, token counting, and error handling. Supports streaming responses and function calling across all providers with normalized schemas.

Maintains an immutable audit log (Journal) of all significant operations: tool executions, blockchain transactions, message sends, and configuration changes. Each journal entry includes timestamp, user, operation type, parameters, and result. The journal is stored in SQLite and queryable via workspace tools. Supports filtering by operation type, user, or date range. Integrates with access control to ensure users can only view their own operations (unless admin).

Integrates with STON.fi and DeDust decentralized exchanges to enable the agent to execute token swaps autonomously. Implements price quote fetching, slippage calculation, and transaction building for both DEXes. Supports jetton-to-jetton swaps and includes built-in tools for querying liquidity pools and swap rates. All swaps are executed via the TON wallet with transaction signing and blockchain confirmation.

Supports NFT operations (querying collections, checking ownership, transferring NFTs) and TON DNS operations (resolving DNS names to addresses, registering domains, managing DNS records). Implements tools for NFT metadata retrieval, transfer execution, and DNS name resolution. All operations are executed via the TON blockchain with transaction signing.

Implements a Deals system that enables the agent to coordinate multi-step workflows involving multiple parties or transactions. A deal is a structured agreement with defined steps, participants, and conditions. The agent can propose deals, track their status, and execute steps as conditions are met. Deals are stored in the workspace and can be queried or modified via tools.

Operates as a real Telegram user account (not a bot) by implementing the MTProto protocol through GramJS Layer 222, enabling the agent to send/receive messages, join groups, manage chats, and access user-only features. Wraps GramJS in a TelegramBridge class that handles session persistence (phone number or session.json), automatic reconnection, event routing to the message processing pipeline, and inline query handling via Grammy. Supports both direct messages and group chats with configurable access control policies per workspace.

Integrates TON blockchain operations through a W5R1 wallet implementation that signs and broadcasts transactions directly from the agent. Supports jetton transfers, NFT operations, DEX swaps (STON.fi, DeDust), DNS operations, and signed message verification. Implements a TON Proxy layer that manages wallet state, validates transaction parameters, and enforces tool-scope permissions before execution. All private keys are stored encrypted in the workspace secrets store, and transactions are auditable via the Journal system.

Provides @teleton-agent/sdk, a TypeScript SDK that enables developers to create plugins that extend the agent with custom tools, LLM providers, or Telegram handlers. Plugins are loaded dynamically at runtime via the plugin system, which discovers plugins from npm packages or local directories, validates their schemas, and registers their tools into the global tool registry. Each plugin has access to namespaced SDK methods (Telegram, TON, Memory, Workspace) and can declare dependencies, permissions, and configuration schemas. Plugins are sandboxed via workspace isolation and subject to module-level permission checks.

Integrates with external MCP servers via stdio, SSE (Server-Sent Events), or HTTP transports, allowing the agent to access tools and resources exposed by MCP-compatible services. The MCP client is initialized during TeletonApp startup, discovers available tools from connected servers, and registers them into the global tool registry alongside built-in tools. Supports multiple concurrent MCP connections, each with independent transport configuration and tool namespacing.

Implements a fine-grained access control system where each tool declares a scope (e.g., 'telegram:send', 'ton:transfer', 'memory:write') and each workspace defines access control policies that grant or deny scopes to specific users or groups. The system enforces permissions at tool execution time via the ToolExecutor, preventing unauthorized operations. Supports role-based access control (RBAC) via admin commands and per-module permission checks. Integrates with input sanitization to prevent prompt injection attacks that might bypass permission checks.

Implements multi-layer input sanitization to defend against prompt injection attacks. Sanitizes user messages before passing them to the LLM, validates tool arguments against declared schemas, and masks sensitive outputs (private keys, transaction hashes) before returning them to the LLM context. Uses a combination of regex-based filtering, schema validation, and observation masking to prevent attackers from manipulating the agent's behavior through crafted prompts or tool outputs.

Manages agent configuration via a single config.yaml file that defines workspace settings (name, personality, LLM provider, embedding provider), Telegram credentials, TON wallet configuration, tool enablement, plugin loading, and access control policies. The configuration is validated against a JSON schema at startup, and changes can be applied via the WebUI configuration interface or CLI. Supports environment variable substitution for secrets (API keys, phone numbers) to enable secure deployment without hardcoding credentials.

Provides an optional Hono + React web interface (localhost:7777 by default) that displays agent status, message history, tool execution logs, and memory statistics in real-time. Enables configuration changes via the UI (LLM provider, tool enablement, access control policies), plugin marketplace browsing, and setup wizard for initial configuration. The dashboard connects to the agent via a REST API and WebSocket for real-time updates.