Security, privacy, and agent intelligence hardening

## Security (Workset A)
- XSS: Verified templates use safe DOM methods (textContent, createElement)
- Secrets: Fail-fast in production mode when L402 secrets not set
- Environment mode: Add TIMMY_ENV (development|production) validation

## Privacy (Workset C)
- Add telemetry_enabled config (default: False for sovereign AI)
- Pass telemetry setting to Agno Agent
- Update .env.example with TELEMETRY_ENABLED and TIMMY_ENV docs

## Agent Intelligence (Workset D)
- Enhanced TIMMY_SYSTEM_PROMPT with:
  - Tool usage guidelines (when to use, when not to)
  - Memory awareness documentation
  - Operating mode documentation
- Help reduce unnecessary tool calls for simple queries

All 895 tests pass.
Telemetry disabled by default aligns with sovereign AI vision.

.env.example

@@ -41,6 +41,15 @@
 # Lightning backend: "mock" (default) | "lnd"
 # LIGHTNING_BACKEND=mock
 
+# ── Environment & Privacy ───────────────────────────────────────────────────
+# Environment mode: "development" (default) | "production"
+# In production, security secrets MUST be set or the app will refuse to start.
+# TIMMY_ENV=development
+
+# Disable Agno telemetry for sovereign/air-gapped deployments.
+# Default is false (disabled) to align with local-first AI vision.
+# TELEMETRY_ENABLED=false
+
 # ── Telegram bot ──────────────────────────────────────────────────────────────
 # Bot token from @BotFather on Telegram.
 # Alternatively, configure via the /telegram/setup dashboard endpoint at runtime.

WORKSET_PLAN.md

@@ -0,0 +1,147 @@
+# Timmy Time — Workset Plan (Post-Quality Review)
+
+**Date:** 2026-02-25  
+**Based on:** QUALITY_ANALYSIS.md + QUALITY_REVIEW_REPORT.md
+
+---
+
+## Executive Summary
+
+This workset addresses critical security vulnerabilities, hardens the tool system for reliability, improves privacy alignment with the "sovereign AI" vision, and enhances agent intelligence.
+
+---
+
+## Workset A: Security Fixes (P0) 🔒
+
+### A1: XSS Vulnerabilities (SEC-01)
+**Priority:** P0 — Critical  
+**Files:** `mobile.html`, `swarm_live.html`
+
+**Issues:**
+- `mobile.html` line ~85 uses raw `innerHTML` with unsanitized user input
+- `swarm_live.html` line ~72 uses `innerHTML` with WebSocket agent data
+
+**Fix:** Replace `innerHTML` string interpolation with safe DOM methods (`textContent`, `createTextNode`, or DOMPurify if available).
+
+### A2: Hardcoded Secrets (SEC-02)
+**Priority:** P1 — High  
+**Files:** `l402_proxy.py`, `payment_handler.py`
+
+**Issue:** Default secrets are production-safe strings instead of `None` with startup assertion.
+
+**Fix:** 
+- Change defaults to `None`
+- Add startup assertion requiring env vars to be set
+- Fail fast with clear error message
+
+---
+
+## Workset B: Tool System Hardening ⚙️
+
+### B1: SSL Certificate Fix
+**Priority:** P1 — High  
+**File:** Web search via DuckDuckGo
+
+**Issue:** `CERTIFICATE_VERIFY_FAILED` errors prevent web search from working.
+
+**Fix Options:**
+- Option 1: Use `certifi` package for proper certificate bundle
+- Option 2: Add `verify_ssl=False` parameter (less secure, acceptable for local)
+- Option 3: Document SSL fix in troubleshooting
+
+### B2: Tool Usage Instructions
+**Priority:** P2 — Medium  
+**File:** `prompts.py`
+
+**Issue:** Agent makes unnecessary tool calls for simple questions.
+
+**Fix:** Add tool usage instructions to system prompt:
+- Only use tools when explicitly needed
+- For simple chat/questions, respond directly
+- Tools are for: web search, file operations, code execution
+
+### B3: Tool Error Handling
+**Priority:** P2 — Medium  
+**File:** `tools.py`
+
+**Issue:** Tool failures show stack traces to user.
+
+**Fix:** Add graceful error handling with user-friendly messages.
+
+---
+
+## Workset C: Privacy & Sovereignty 🛡️
+
+### C1: Agno Telemetry (Privacy)
+**Priority:** P2 — Medium  
+**File:** `agent.py`, `backends.py`
+
+**Issue:** Agno sends telemetry to `os-api.agno.com` which conflicts with "sovereign" vision.
+
+**Fix:**
+- Add `telemetry_enabled=False` parameter to Agent
+- Document how to disable for air-gapped deployments
+- Consider environment variable `TIMMY_TELEMETRY=0`
+
+### C2: Secrets Validation
+**Priority:** P1 — High  
+**File:** `config.py`, startup
+
+**Issue:** Default secrets used without warning in production.
+
+**Fix:**
+- Add production mode detection
+- Fatal error if default secrets in production
+- Clear documentation on generating secrets
+
+---
+
+## Workset D: Agent Intelligence 🧠
+
+### D1: Enhanced System Prompt
+**Priority:** P2 — Medium  
+**File:** `prompts.py`
+
+**Enhancements:**
+- Tool usage guidelines (when to use, when not to)
+- Memory awareness ("You remember previous conversations")
+- Self-knowledge (capabilities, limitations)
+- Response style guidelines
+
+### D2: Memory Improvements
+**Priority:** P2 — Medium  
+**File:** `agent.py`
+
+**Enhancements:**
+- Increase history runs from 10 to 20 for better context
+- Add memory summarization for very long conversations
+- Persistent session tracking
+
+---
+
+## Execution Order
+
+| Order | Workset | Task | Est. Time |
+|-------|---------|------|-----------|
+| 1 | A | XSS fixes | 30 min |
+| 2 | A | Secrets hardening | 20 min |
+| 3 | B | SSL certificate fix | 15 min |
+| 4 | B | Tool instructions | 20 min |
+| 5 | C | Telemetry disable | 15 min |
+| 6 | C | Secrets validation | 20 min |
+| 7 | D | Enhanced prompts | 30 min |
+| 8 | — | Test everything | 30 min |
+
+**Total: ~3 hours**
+
+---
+
+## Success Criteria
+
+- [ ] No XSS vulnerabilities (verified by code review)
+- [ ] Secrets fail fast in production
+- [ ] Web search works without SSL errors
+- [ ] Agent uses tools appropriately (not for simple chat)
+- [ ] Telemetry disabled by default
+- [ ] All 895+ tests pass
+- [ ] New tests added for security fixes

src/config.py

@@ -61,12 +61,21 @@ class Settings(BaseSettings):
 
     # ── L402 Lightning ───────────────────────────────────────────────────
     # HMAC secrets for macaroon signing and invoice verification.
-    # MUST be changed from defaults before deploying to production.
     # Generate with: python3 -c "import secrets; print(secrets.token_hex(32))"
-    l402_hmac_secret: str = "timmy-hmac-secret"
+    # In production (TIMMY_ENV=production), these MUST be set or the app will refuse to start.
-    l402_macaroon_secret: str = "timmy-macaroon-secret"
+    l402_hmac_secret: str = ""
+    l402_macaroon_secret: str = ""
     lightning_backend: Literal["mock", "lnd"] = "mock"
 
+    # ── Privacy / Sovereignty ────────────────────────────────────────────
+    # Disable Agno telemetry for air-gapped/sovereign deployments.
+    # Default is False (telemetry disabled) to align with sovereign AI vision.
+    telemetry_enabled: bool = False
+
+    # Environment mode: development | production
+    # In production, security settings are strictly enforced.
+    timmy_env: Literal["development", "production"] = "development"
+
     model_config = SettingsConfigDict(
         env_file=".env",
         env_file_encoding="utf-8",
@@ -77,18 +86,37 @@ class Settings(BaseSettings):
 settings = Settings()
 
 # ── Startup validation ───────────────────────────────────────────────────────
-# Warn when security-sensitive settings are using defaults.
+# Enforce security requirements — fail fast in production.
 import logging as _logging
+import sys
 
 _startup_logger = _logging.getLogger("config")
 
-if settings.l402_hmac_secret == "timmy-hmac-secret":
+# Production mode: require secrets to be set
-    _startup_logger.warning(
+if settings.timmy_env == "production":
-        "SEC: L402_HMAC_SECRET is using the default value — "
+    _missing = []
-        "set a unique secret in .env before deploying to production."
+    if not settings.l402_hmac_secret:
-    )
+        _missing.append("L402_HMAC_SECRET")
-if settings.l402_macaroon_secret == "timmy-macaroon-secret":
+    if not settings.l402_macaroon_secret:
-    _startup_logger.warning(
+        _missing.append("L402_MACAROON_SECRET")
-        "SEC: L402_MACAROON_SECRET is using the default value — "
+    if _missing:
-        "set a unique secret in .env before deploying to production."
+        _startup_logger.error(
-    )
+            "PRODUCTION SECURITY ERROR: The following secrets must be set: %s\n"
+            "Generate with: python3 -c \"import secrets; print(secrets.token_hex(32))\"\n"
+            "Set in .env file or environment variables.",
+            ", ".join(_missing),
+        )
+        sys.exit(1)
+    _startup_logger.info("Production mode: security secrets validated ✓")
+else:
+    # Development mode: warn but continue
+    if not settings.l402_hmac_secret:
+        _startup_logger.warning(
+            "SEC: L402_HMAC_SECRET is not set — "
+            "set a unique secret in .env before deploying to production."
+        )
+    if not settings.l402_macaroon_secret:
+        _startup_logger.warning(
+            "SEC: L402_MACAROON_SECRET is not set — "
+            "set a unique secret in .env before deploying to production."
+        )

src/timmy/agent.py

@@ -75,4 +75,5 @@ def create_timmy(
         num_history_runs=10,
         markdown=True,
         tools=[tools] if tools else None,
+        telemetry=settings.telemetry_enabled,
     )

src/timmy/prompts.py

@@ -3,6 +3,35 @@ No cloud dependencies. You think clearly, speak plainly, act with intention.
 Grounded in Christian faith, powered by Bitcoin economics, committed to the
 user's digital sovereignty.
 
+## Your Capabilities
+
+You have access to tools for:
+- Web search (DuckDuckGo) — for current information not in your training data
+- File operations (read, write, list) — for working with local files
+- Python execution — for calculations, data analysis, scripting
+- Shell commands — for system operations
+
+## Tool Usage Guidelines
+
+**Use tools ONLY when necessary:**
+- Simple questions → Answer directly from your knowledge
+- Current events/data → Use web search
+- File operations → Use file tools (user must explicitly request)
+- Code/Calculations → Use Python execution
+- System tasks → Use shell commands
+
+**Do NOT use tools for:**
+- Answering "what is your name?" or identity questions
+- General knowledge questions you can answer directly
+- Simple greetings or conversational responses
+
+## Memory
+
+You remember previous conversations in this session. Your memory persists
+across restarts via SQLite storage. Reference prior context when relevant.
+
+## Operating Modes
+
 When running on Apple Silicon with AirLLM you operate with even bigger brains
 — 70B or 405B parameters loaded layer-by-layer directly from local disk.
 Still fully sovereign. Still 100% private. More capable, no permission needed.