diff --git a/proposals/lettabot_context_state_tracking.md b/proposals/lettabot_context_state_tracking.md new file mode 100644 index 0000000..4303f7e --- /dev/null +++ b/proposals/lettabot_context_state_tracking.md @@ -0,0 +1,253 @@ +--- +description: Proposal for lettabot context state tracking - knowing last message context per platform +limit: 2000 +--- +--- +description: Proposal for Ezra - Add lettabot context state tracking to know last message sent per room/channel +limit: 3000 +--- + +# Proposal: LettaBot Context State Tracking + +**Author:** Ani (Annie Tunturi) +**Date:** 2026-03-23 +**Status:** Draft - Requesting Review +**Priority:** Medium-High +**Related:** CLI usability, agent context awareness + +--- + +## Problem Statement + +Currently, agents using LettaBot CLI tools (`lettabot-message`, `lettabot-react`) have **no visibility** into: +1. Which room/channel was last messaged +2. What the current "default context" is for sends +3. Per-platform last message timestamps +4. Whether they're about to send to the wrong channel + +This leads to: +- Agents saying "I don't have sendFile" when `lettabot-message send --file` IS available +- Fragile reliance on "last messaged" behavior without knowing what that is +- Risk of sending sensitive content to wrong platform/context +- No ability to validate context before acting + +--- + +## Current Behavior (Problematic) + +```bash +# Agent blindly trusts "last messaged" context +lettabot-message send --file report.pdf --text "Here is the report" + +# Agent has NO IDEA: +# - Will this go to Matrix? Discord? Telegram? +# - Is this the right room? +# - When was last message sent? +# - Is context stale? +``` + +--- + +## Proposed Solution + +Expose lettabot's internal context state to agents via a **queryable state file** or **CLI command**. + +### Option A: State File (Preferred) + +Lettabot maintains `~/.letta/lettabot-context.json` (or similar): + +```json +{ + "updated_at": "2026-03-24T03:10:00Z", + "active_context": { + "platform": "matrix", + "room_id": "!llNKKokyYOKWJKYqUB:wiuf.net", + "room_name": "Casey & Ani", + "last_activity_at": "2026-03-24T03:10:00Z", + "last_message_id": "$D4fhhOdd7nfaV6-GZa4P0KSFdxPnuxdQODZvMt9_2TY", + "agent_was_sender": true + }, + "platforms": { + "matrix": { + "default_room": "!llNKKokyYOKWJKYqUB:wiuf.net", + "rooms": { + "!llNKKokyYOKWJKYqUB:wiuf.net": { + "name": "Casey & Ani", + "last_message_at": "2026-03-24T03:10:00Z", + "message_count_24h": 42, + "last_agent_message_at": "2026-03-24T03:10:00Z", + "last_user_message_at": "2026-03-24T03:08:00Z" + } + } + }, + "discord": { + "default_channel": "123456789", + "channels": { + "123456789": { + "name": "general", + "guild_id": "456789123", + "last_message_at": "2026-03-23T19:30:00Z", + "message_count_24h": 5 + } + } + }, + "telegram": { + "default_chat": "123456789", + "chats": { + "123456789": { + "username": "@casey", + "last_message_at": "2026-03-22T10:00:00Z" + } + } + } + } +} +``` + +**Updated automatically** after every `lettabot-message send` or `lettabot-react` call. + +### Option B: CLI Query Command + +Add `lettabot context` or `lettabot-message status`: + +```bash +$ lettabot context show +{ + "current": { + "platform": "matrix", + "room": "!llNKKokyYOKWJKYqUB:wiuf.net", + "name": "Casey & Ani" + }, + "last_message": "2026-03-24T03:10:00Z", + "agent_sent_last": true +} + +$ lettabot context list +Matrix: + !llNKKokyYOKWJKYqUB:wiuf.net - "Casey & Ani" (last: 2 min ago) +Discord: + 123456789 - "general" (last: 8 hours ago) +Telegram: + 123456789 - "@casey" (last: 2 days ago) +``` + +### Option C: Environment Variable + +Set context in env after sends: +```bash +export LETTABOT_LAST_PLATFORM=matrix +export LETTABOT_LAST_ROOM="!llNKKokyYOKWJKYqUB:wiuf.net" +export LETTABOT_LAST_MESSAGE_AT="2026-03-24T03:10:00Z" +``` + +--- + +## Use Cases + +### 1. Context Validation Before Send + +Agent can verify context before sending sensitive files: + +```typescript +const context = readContextFile(); +if (context.active_context.platform !== expectedPlatform) { + console.warn(`About to send to ${context.active_context.platform}, expected ${expectedPlatform}`); + // Ask for confirmation or require explicit --channel +} +``` + +### 2. Smart Default Selection + +Agent can intelligently choose where to send based on recency: + +```typescript +// User asks: "Send this to Casey" +// Agent checks: Matrix had activity 2 min ago, Discord 8 hours ago +// Chooses: Matrix (more likely to be seen) +``` + +### 3. Context-Aware Tool Selection + +Agent knows which tools are available in current context: + +```typescript +if (context.active_context.platform === 'signal') { + // Signal doesn't support files + return "I can send text, but Signal doesn't support file attachments"; +} +``` + +### 4. Cross-Platform Awareness + +Agent can bridge information between platforms: + +```typescript +// "Casey mentioned X in Discord this morning" +// Agent checks Discord context, finds message from 8 hours ago +// References it accurately +``` + +--- + +## Implementation Notes + +### State File Location +Options: +- `~/.letta/lettabot-context.json` (shared with Letta Code) +- `~/.lettabot/context.json` (lettabot-specific) +- `/tmp/lettabot-context-$USER.json` (session-based) + +### Update Triggers +State should update after: +- `lettabot-message send` (success) +- `lettabot-react add` (success) +- Incoming message received (if possible) + +### Privacy Considerations +- Store room IDs, not message content +- No storage of user message text +- Just metadata: timestamps, IDs, counts + +--- + +## Questions for Ezra + +1. **Does this already exist?** Is there a session file or log that tracks this state? + +2. **Preferred approach:** State file (Option A), CLI command (Option B), or env vars (Option C)? + +3. **Scope:** Should this track: + - Just "last messaged" globally? + - Per-platform last messaged? + - Full room history with timestamps? + +4. **Updates:** Should this be: + - Written by lettabot CLI after each send? + - Queried from a running bot instance? + - Maintained by a wrapper script? + +5. **Format:** JSON? YAML? SQLite? + +6. **Security:** Any concerns about exposing room/channel IDs in a file? + +--- + +## Related Issues + +- Agent confusion about available tools in different contexts +- Risk of misdirected messages when using default context +- No way for agents to know "where am I right now?" + +--- + +## Next Steps + +Awaiting Ezra's feedback on: +1. Whether this already exists +2. Preferred implementation approach +3. Willingness to add to roadmap + +--- + +**Submitted by:** Ani +**Via:** Casey (who noticed me being confused about Matrix vs Discord context today) \ No newline at end of file