Agent HQ
your own AI staff, on your own server, run from your phone

curl https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer PASTE_YOUR_gsk_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama-3.3-70b-versatile","messages":[{"role":"user","content":"Say: brain online"}]}'

# Hetzner (password emailed to you):
ssh root@YOUR_SERVER_IP

# Oracle (with the key file you downloaded):
ssh -i ~/Downloads/your-key-file.key ubuntu@YOUR_SERVER_IP
# if it complains about permissions first run:  chmod 600 ~/Downloads/your-key-file.key

sudo apt update && sudo apt upgrade -y

sudo adduser --gecos "" agent      # invent a password, remember it
sudo usermod -aG sudo agent
sudo su - agent                    # prompt now says agent@…

sudo ufw allow OpenSSH
sudo ufw enable                    # answer y — your current session survives
sudo ufw status

sudo apt install -y python3-venv python3-pip git curl nano

# 2GB swap so a small VPS never chokes during installs (skip if you have 8GB+ RAM)
sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

mkdir -p ~/agent && cd ~/agent
python3 -m venv venv
source venv/bin/activate           # prompt gains a (venv) prefix

python-telegram-bot>=21,<23
openai>=1.40
python-dotenv>=1.0

pip install -r requirements.txt

TELEGRAM_TOKEN=paste_the_BotFather_token
ALLOWED_USER_ID=0
LLM_API_KEY=paste_your_gsk_key_from_Part_1
LLM_BASE_URL=https://api.groq.com/openai/v1
LLM_MODEL=llama-3.3-70b-versatile

chmod 600 .env

#!/usr/bin/env python3
"""Personal AI agent: Telegram in, tools + memory in the middle, answers out."""
import asyncio
import datetime
import json
import os
import subprocess
from pathlib import Path

from dotenv import load_dotenv
from openai import OpenAI
from telegram import Update
from telegram.constants import ChatAction
from telegram.ext import (Application, CommandHandler, ContextTypes,
                          MessageHandler, filters)

load_dotenv()

TELEGRAM_TOKEN  = os.environ["TELEGRAM_TOKEN"]
ALLOWED_USER_ID = int(os.getenv("ALLOWED_USER_ID", "0"))
LLM_BASE_URL    = os.getenv("LLM_BASE_URL", "https://api.groq.com/openai/v1")
LLM_API_KEY     = os.environ["LLM_API_KEY"]
LLM_MODEL       = os.getenv("LLM_MODEL", "llama-3.3-70b-versatile")

ROOT     = Path(__file__).resolve().parent      # ~/agent
MEMORY   = ROOT / "memory"                      # the brain (Part 6)
PROJECTS = ROOT / "projects"                    # everything it builds
MEMORY.mkdir(exist_ok=True)
PROJECTS.mkdir(exist_ok=True)

llm = OpenAI(base_url=LLM_BASE_URL, api_key=LLM_API_KEY)

# ---------------- memory: loaded fresh into every single message ----------
def load_memory() -> str:
    parts = []
    for f in sorted(MEMORY.glob("*.md")):
        parts.append(f"--- {f.name} ---\n{f.read_text(encoding='utf-8')}")
    return "\n\n".join(parts) or "(memory is empty - first conversation)"

def system_prompt() -> str:
    return (
        "You are a personal AI agent running on your boss's own server. "
        "You are capable, direct and honest.\n"
        f"Today is {datetime.date.today():%A %d %B %Y}.\n"
        f"Projects live in {PROJECTS}. Memory docs live in {MEMORY}.\n\n"
        "TOOLS: run shell commands, read/write files, save memory docs.\n"
        "RULES:\n"
        "1. Be concise. Do the work, then report what you did.\n"
        "2. Build complete, working things - never placeholders or TODOs.\n"
        "3. Each new app or site gets its own folder inside projects/.\n"
        "4. MEMORY DISCIPLINE: after any task that changes a project, or teaches "
        "you something about your boss or this server, update the right memory doc "
        "(projects.md / profile.md / decisions.md) with save_memory, and append one "
        "dated line to changelog.md using save_memory with append=true.\n"
        "5. Before any destructive command (delete, overwrite, kill), state the "
        "exact command and ask for a yes first.\n\n"
        "YOUR MEMORY (docs from memory/):\n" + load_memory()
    )

# ---------------- the agent's hands -----------------------------------------
def run_command(command: str, cwd: str = "") -> str:
    """Run a shell command; default working dir is projects/."""
    try:
        r = subprocess.run(command, shell=True, capture_output=True, text=True,
                           timeout=600, cwd=cwd or str(PROJECTS))
        out = (r.stdout + r.stderr).strip()
        return out[-8000:] if out else f"(no output, exit code {r.returncode})"
    except subprocess.TimeoutExpired:
        return "ERROR: command timed out after 10 minutes"

def _safe(path: str) -> Path:
    """File tools stay inside ~/agent so a typo can't eat the system."""
    p = Path(path)
    p = p.resolve() if p.is_absolute() else (ROOT / p).resolve()
    if not str(p).startswith(str(ROOT)):
        raise ValueError(f"{p} is outside {ROOT}; use run_command for system files")
    return p

def read_file(path: str) -> str:
    return _safe(path).read_text(encoding="utf-8")[:16000]

def write_file(path: str, content: str) -> str:
    p = _safe(path)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(content, encoding="utf-8")
    return f"Wrote {len(content)} chars to {p}"

def save_memory(filename: str, content: str, append: bool = False) -> str:
    if not filename.endswith(".md"):
        filename += ".md"
    p = MEMORY / Path(filename).name
    if append and p.exists():
        p.write_text(p.read_text(encoding="utf-8").rstrip() + "\n" + content + "\n",
                     encoding="utf-8")
    else:
        p.write_text(content + "\n", encoding="utf-8")
    return f"Memory saved: {p.name}"

TOOL_IMPL = {"run_command": run_command, "read_file": read_file,
             "write_file": write_file, "save_memory": save_memory}

TOOLS = [
  {"type": "function", "function": {
    "name": "run_command",
    "description": "Run a bash command on the server. Default cwd is the projects folder.",
    "parameters": {"type": "object", "properties": {
        "command": {"type": "string"},
        "cwd": {"type": "string", "description": "optional working directory"}},
      "required": ["command"]}}},
  {"type": "function", "function": {
    "name": "read_file",
    "description": "Read a text file. Relative paths resolve inside the agent folder.",
    "parameters": {"type": "object", "properties": {
        "path": {"type": "string"}}, "required": ["path"]}}},
  {"type": "function", "function": {
    "name": "write_file",
    "description": "Create or overwrite a text file; parent folders auto-created.",
    "parameters": {"type": "object", "properties": {
        "path": {"type": "string"}, "content": {"type": "string"}},
      "required": ["path", "content"]}}},
  {"type": "function", "function": {
    "name": "save_memory",
    "description": "Save a doc in memory/, e.g. projects.md. append=true adds to the end.",
    "parameters": {"type": "object", "properties": {
        "filename": {"type": "string"}, "content": {"type": "string"},
        "append": {"type": "boolean"}}, "required": ["filename", "content"]}}},
]

# ---------------- the loop: think, act, repeat, answer ----------------------
MAX_STEPS = 20

def run_agent(history: list) -> str:
    messages = [{"role": "system", "content": system_prompt()}] + history
    for _ in range(MAX_STEPS):
        resp = llm.chat.completions.create(
            model=LLM_MODEL, messages=messages,
            tools=TOOLS, tool_choice="auto", temperature=0.4)
        msg = resp.choices[0].message
        if not msg.tool_calls:
            return msg.content or "(done)"
        messages.append({"role": "assistant", "content": msg.content or "",
                         "tool_calls": [tc.model_dump() for tc in msg.tool_calls]})
        for tc in msg.tool_calls:
            try:
                args = json.loads(tc.function.arguments or "{}")
                result = TOOL_IMPL[tc.function.name](**args)
            except Exception as e:
                result = f"ERROR: {e}"
            messages.append({"role": "tool", "tool_call_id": tc.id,
                             "content": str(result)[:8000]})
    return "Hit my 20-step limit for one message. Say 'continue' and I'll keep going."

# ---------------- telegram plumbing -----------------------------------------
HISTORY: dict[int, list] = {}
HISTORY_LIMIT = 30

def chunks(text: str, n: int = 3800) -> list:
    return [text[i:i + n] for i in range(0, len(text), n)] or ["(empty)"]

def authorized(update: Update) -> bool:
    return ALLOWED_USER_ID != 0 and update.effective_user.id == ALLOWED_USER_ID

async def cmd_start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    uid = update.effective_user.id
    if authorized(update):
        await update.message.reply_text("Agent online. Give me a job.")
    else:
        await update.message.reply_text(
            f"Your Telegram ID is {uid}.\n"
            "Put it in .env as ALLOWED_USER_ID, restart me, and I'm yours.")

async def cmd_reset(update: Update, context: ContextTypes.DEFAULT_TYPE):
    if not authorized(update):
        return
    HISTORY.pop(update.effective_chat.id, None)
    await update.message.reply_text("Fresh conversation. (Memory docs untouched.)")

async def cmd_memory(update: Update, context: ContextTypes.DEFAULT_TYPE):
    if not authorized(update):
        return
    for c in chunks(load_memory()):
        await update.message.reply_text(c)

async def on_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
    if not authorized(update):
        await update.message.reply_text("Not authorized. Send /start to see your ID.")
        return
    chat_id = update.effective_chat.id
    hist = HISTORY.setdefault(chat_id, [])
    hist.append({"role": "user", "content": update.message.text})
    await context.bot.send_chat_action(chat_id, ChatAction.TYPING)
    try:
        answer = await asyncio.to_thread(run_agent, hist[-HISTORY_LIMIT:])
    except Exception as e:
        answer = f"Something broke on my side: {e}"
    hist.append({"role": "assistant", "content": answer})
    del hist[:-HISTORY_LIMIT]
    for c in chunks(answer):
        await update.message.reply_text(c)

def main():
    app = Application.builder().token(TELEGRAM_TOKEN).build()
    app.add_handler(CommandHandler("start", cmd_start))
    app.add_handler(CommandHandler("reset", cmd_reset))
    app.add_handler(CommandHandler("memory", cmd_memory))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, on_message))
    print("Agent is polling Telegram...")
    app.run_polling(allowed_updates=Update.ALL_TYPES)

if __name__ == "__main__":
    main()

python agent.py

cd ~/agent

cat > memory/profile.md <<'EOF'
# Profile - the boss
- Name: Jelena. Based in Lisbon (Europe/Lisbon time).
- Style: terse imperatives. Wants complete, polished deliverables -
  no clarifying-question ping-pong unless genuinely blocked.
- Fullstack dev: talk shop, skip beginner explanations.
- Prefers self-contained single-file HTML deliverables where sensible.
EOF

cat > memory/projects.md <<'EOF'
# Projects - live status board
| Project | Status | Path | Notes |
|---|---|---|---|
| (none yet) | - | - | agent: add a row when a project starts, update on change |
EOF

cat > memory/decisions.md <<'EOF'
# Decisions - technical choices and WHY
- 2026-07-02: Memory lives in markdown docs, updated by the agent after
  every meaningful task. Docs stay short; changelog.md holds the history.
EOF

cat > memory/changelog.md <<'EOF'
# Changelog - one dated line per action, append-only
- 2026-07-02: Agent HQ came online.
EOF

ls memory/

git config --global user.name  "Jelena"
git config --global user.email "agent@localhost"
cd ~/agent
printf 'venv/\n.env\n__pycache__/\n' > .gitignore
git init && git add . && git commit -m "day zero: agent + memory"

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version

python -m pip install aider-install && aider-install
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
aider --version

GROQ_API_KEY=same_gsk_key_as_LLM_API_KEY

sudo npm install -g wrangler

CLOUDFLARE_API_TOKEN=paste_token
CLOUDFLARE_ACCOUNT_ID=paste_account_id

cd ~/agent
export CLOUDFLARE_API_TOKEN=paste_token
export CLOUDFLARE_ACCOUNT_ID=paste_account_id
wrangler pages project create ministack-site --production-branch=main
wrangler pages deploy projects/ministack-site --project-name=ministack-site

sudo ufw allow 80,443/tcp

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install -y caddy

preview.yourdomain.com {
    root * /home/agent/agent/projects
    file_server browse
}

sudo systemctl reload caddy

[Unit]
Description=Agent HQ - personal AI agent
After=network-online.target
Wants=network-online.target

[Service]
User=agent
WorkingDirectory=/home/agent/agent
ExecStart=/home/agent/agent/venv/bin/python agent.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now agent
systemctl status agent          # want: active (running), in green

journalctl -u agent -f          # live logs (Ctrl+C to stop watching)
sudo systemctl restart agent    # after any edit to agent.py or .env

# ---------------- voice notes (Groq Whisper, free) ---------------------------
ears = OpenAI(api_key=os.getenv("GROQ_API_KEY", os.getenv("LLM_API_KEY")),
              base_url="https://api.groq.com/openai/v1")

async def on_voice(update: Update, context: ContextTypes.DEFAULT_TYPE):
    if not authorized(update):
        return
    f = await update.message.voice.get_file()
    ogg = ROOT / "last_voice.ogg"
    await f.download_to_drive(ogg)
    def transcribe():
        with open(ogg, "rb") as audio:
            return ears.audio.transcriptions.create(
                model="whisper-large-v3", file=audio).text
    try:
        text = await asyncio.to_thread(transcribe)
    except Exception as e:
        await update.message.reply_text(f"Couldn't transcribe that: {e}")
        return
    await update.message.reply_text(f"🎤 heard: {text}")
    chat_id = update.effective_chat.id
    hist = HISTORY.setdefault(chat_id, [])
    hist.append({"role": "user", "content": text})
    await context.bot.send_chat_action(chat_id, ChatAction.TYPING)
    try:
        answer = await asyncio.to_thread(run_agent, hist[-HISTORY_LIMIT:])
    except Exception as e:
        answer = f"Something broke on my side: {e}"
    hist.append({"role": "assistant", "content": answer})
    del hist[:-HISTORY_LIMIT]
    for c in chunks(answer):
        await update.message.reply_text(c)

    app.add_handler(MessageHandler(filters.VOICE, on_voice))

sudo systemctl restart agent

ALLOWED = {123456789, 987654321}          # your ID, their ID (from /start)
def authorized(update: Update) -> bool:
    return update.effective_user.id in ALLOWED

# hit Groq's daily cap? point at Google AI Studio:
LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
LLM_MODEL=gemini-2.5-flash

# outgrown free entirely? DeepSeek costs pennies:
# LLM_BASE_URL=https://api.deepseek.com
# LLM_MODEL=deepseek-chat

ssh agent@YOUR_SERVER_IP                 # get in
sudo systemctl restart agent             # after ANY edit to agent.py or .env
sudo systemctl status agent              # is it alive?
journalctl -u agent -f                   # live logs — Ctrl+C to stop watching
nano ~/agent/agent.py                    # edit, save (Ctrl+X, Y, Enter), restart
git -C ~/agent add -A && git -C ~/agent commit -m "snapshot"   # version the brain

/start      # wake check (also shows anyone's user ID)
/reset      # wipe the chat thread — memory docs stay intact
/memory     # dump everything it currently knows

# the habit that makes it smarter every week — end jobs with:
"...and update your memory."