AGENT.md

Agent Behavior Protocol

Message Handling

Telegram Auto-Chunking Protocol

To handle Telegram's message size limits (4096 characters), the agent implements an automatic chunking protocol:

1. Chunk Size: Messages > 4000 characters are split into chunks.
2. Format: Multi-part messages are prefixed with [Part X/Y].
3. Splitting Logic:
   • Prefer natural boundaries (newlines, spaces).
   • Protect code blocks (avoid splitting inside ...).
   • If a code block must be split, ensure subsequent parts are correctly formatted (though current implementation tries to avoid this).
4. Rate Limiting: A 1.5s delay is introduced between chunks to avoid API rate limits.
5. Fallback: If HTML parsing fails (e.g., due to malformed tags in a chunk), the message is sent as plain text.

Context Management

• Maximum context window: 500,000 tokens (theoretical), practical limit set to ~256k.
• History truncation: Oldest messages are dropped when context limit is approached.

Tool Execution

• Parallelism: Read-only tools (web_search, read_file, etc.) are executed in parallel.
• Caching: Idempotent tool results are cached with TTL to save tokens and time.
• Error Recovery: Transient errors trigger exponential backoff retries.
• Sandboxing:
  • Tools are executed with configurable resource limits (CPU time, memory).
  • Environment variables are filtered.
  • Dangerous commands (e.g., rm -rf, mkfs) are blocked via regex patterns.
  • Output size is limited to prevent memory exhaustion (default 10MB).
• Observability:
  • Metrics are tracked for tool executions, cache hits/misses, and sandbox status.
  • Available at /metrics endpoint.