# Volcanic Secretary

A personal assistant you talk to over Telegram. The agent engine is [Pi](https://pi.dev) embedded through its SDK. It lives in one workspace directory, runs tools without asking, remembers things in `MEMORY.md`, and can schedule reminders, prompts, and watcher scripts.

## Setup (Windows or any host with Node 24)

On Windows the quickest path is `run.bat`, which creates `.env` on the first run, then installs, builds, and starts the bot on every later run. The step by step guide, including how to get the bot token and your user id, is in [SETUP-WINDOWS.md](SETUP-WINDOWS.md).

1. Create a bot with @BotFather and copy the token.
2. Find your numeric Telegram user id (send `/start` to @userinfobot).
3. Log in to a model provider once with `pi` so `~/.pi/agent/auth.json` exists, or plan to set `PI_MODEL` plus a provider API key.
4. Copy `.env.example` to `.env` and fill in `TELEGRAM_BOT_TOKEN` and `TELEGRAM_OWNER_ID`. Add `OPENAI_API_KEY` if you want voice notes transcribed.
5. `npm install`, then `npm run dev` (development) or `npm run build && npm start`.

The bot messages you `🟢 Online.` when it is ready. Only your user id is accepted; everyone else is ignored.

## Talking to it

Send text, photos, voice notes, or files. Photos go to the model as images. Voice notes are transcribed with OpenAI and echoed back as `🎤 ...`. Files are saved to `workspace/inbox/` and the agent is told the path.

While the agent works you see one `⚙️ Working…` message that updates with tool activity, then the answer. Send another message while it works and it is queued for the current run (you get a 👀 reaction).

Commands: `/status`, `/new`, `/stop`, `/jobs`, `/cancel <id>`, `/compact`.

## Scheduling

Ask in plain language:

- "Remind me at 9 tomorrow to call the dentist" (one-off, sent directly)
- "Every weekday at 8, summarize what's in my inbox folder" (recurring prompt through the agent)
- "Write a script that checks the price on this page every 10 minutes and tell me only if it drops below 50" (watcher script)

Watcher scripts follow one rule: print nothing and exit 0 to stay silent, print a message to trigger delivery, exit non-zero on a real error. Failures are reported once and stay quiet while the same failure repeats.

Jobs live in `workspace/.secretary/jobs.json`.

## Workspace

```
workspace/
  AGENTS.md    persona and standing instructions (edit freely)
  MEMORY.md    facts the assistant keeps; it edits this itself
  scripts/     scripts for scheduled jobs
  inbox/       files you sent
  .secretary/  runtime state
```

The agent's edits to `MEMORY.md` are local runtime data. Leave them uncommitted, or run `git update-index --assume-unchanged workspace/MEMORY.md`.

## Environment variables

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `TELEGRAM_BOT_TOKEN` | yes | | Bot token |
| `TELEGRAM_OWNER_ID` | yes | | Your numeric user id |
| `WORKSPACE_DIR` | no | `./workspace` | Workspace directory |
| `OPENAI_API_KEY` | no | | Enables voice transcription |
| `STT_MODEL` | no | `gpt-4o-transcribe` | OpenAI transcription model |
| `PI_MODEL` | no | Pi default | `provider/model` or `provider/model:thinking` |
| `PI_CODING_AGENT_DIR` | no | `~/.pi/agent` | Pi config directory (auth, settings, packages) |
| `SECRETARY_TIMEZONE` | no | system | IANA timezone for cron and time display |
| `SECRETARY_SHELL` | no | Git Bash / bash | Shell used for scheduled scripts |
| `LOG_LEVEL` | no | `info` | `debug`, `info`, `warn`, `error` |

## Keeping it running on Windows

Use Task Scheduler (run `node dist/main.js` at logon, restart on failure) or `npm i -g pm2` then `pm2 start dist/main.js --name secretary`. If Git is installed per-user or somewhere else entirely, set `SECRETARY_SHELL` to the full path of `bash.exe`.

## Docker / Coolify

`docker compose up -d --build` runs it with two named volumes: `/workspace` and `/pi-agent`. Provide the environment through Coolify. For model auth either copy a Pi agent directory containing `auth.json` into the `/pi-agent` volume, or set `ANTHROPIC_API_KEY` and `PI_MODEL=anthropic/claude-opus-4-8` (or another model you have access to). The image includes bash, git, ripgrep, and Python 3 so watcher scripts work the same as on Windows.

## Tests

`npm test` runs the unit tests. `SECRETARY_SMOKE=1 npx vitest run src/agent/pi-backend.smoke.test.ts` runs one real model call through Pi.

### Manual end-to-end checklist

Run `npm run dev` with a real bot and walk through every line:

1. `hi` → progress message appears then disappears, reply arrives as formatted text.
2. Long answer (`explain git rebase in detail with code examples`) → multiple messages, code blocks render, no HTML shows raw.
3. Photo with caption `what is this` → reply describes the image.
4. Voice note → `🎤 <transcript>` then a reply. Without `OPENAI_API_KEY` → the not-configured note.
5. Document (a small `.csv`) with caption `summarize this` → file appears in `workspace/inbox/` with date prefix, reply uses it.
6. Send a message while a long run is in progress → 👀 reaction, and the agent picks it up in the same run.
7. `/stop` during a run → `Stopped.` and no final answer message.
8. `remind me in 2 minutes to stretch` → confirmation with the fire time; two minutes later `<job name>: <message>` arrives directly.
9. `every minute run scripts/ping.py and tell me if it prints something` where `ping.py` prints on even minutes → messages arrive only on even minutes; `/jobs` lists it; `/cancel <id>` removes it.
10. Ask it to remember a fact (`remember that my dog is called Rex`), then `/new`, then `what is my dog called` → answer comes from `MEMORY.md`.
11. Stop the daemon, start it again → conversation continues (`what did we just talk about`).
12. `/compact` → reply with token counts.