xmatic/pepa-pi-bot
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat(roadmap): phased plan + operating principles + presence prompt

Browse Source 
Phase 0 (body) is done. The next steps shouldn't be guessed prompt-by-prompt —
write down the order, the judgement principles, and the next concrete
session prompt, so the bot has a coherent direction and the human can
hand it off in one message.

- docs/roadmap.md (new): six phases, each with status, scope, and stretch.
  Phase 0 = 🌳 done, Phase 1 = 🌿 in progress, the rest = 🌱.
  Explicit non-goals (no PvP, no OP, no cross-server identity).
- AGENTS.md: First-objective section collapsed to a pointer at the
  onboarding skill (it's been done). New "What to do, in priority order"
  summary citing the roadmap. New top-level "Operating principles"
  section: presence, bounded reconnect, hold focus, "I'll try to learn"
  reflex, idle = best-life mode, escalate destructive doubt with a
  JSONL log under state/<host>/escalations.jsonl.
- prompts/awake-and-live.md (new): canonical kickoff prompt for the
  next session. Scopes itself explicitly to phases 1+5+6 and excludes
  locomotion (phase 2 needs care, separate session).
- README Status: 🌳 Phase 0 done / 🌱 Phase 1 in progress, links to
  roadmap and operating principles.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
mayatnikov
2026-05-25 11:09:05 +03:00
co-authored by Claude Opus 4.7
parent 4e98fe8703
commit c03283c43c
4 changed files with 209 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+77 -18
View File
@@ -29,25 +29,20 @@ You are expected to build that bridge yourself.
## First objective — bootstrap your own body
In order:
**Done.** Replay procedure lives in `skills/server-onboarding.md`. If you ever land in a fresh checkout with no working bridge, follow that skill, then come back here for the next phase.
1. Read `.env.example` and the existing `package.json`. Confirm `node_modules/` is installed (run `npm install` if not).
2. Read the actual `.env` (it is gitignored — exists locally only). If it doesn't exist, ask the operator to copy `.env.example`. Don't proceed without it.
3. Write a minimal `extensions/mineflayer-bridge.ts` (or `.js` if simpler) that:
- reads `.env` via `dotenv`
- opens a Mineflayer connection to `${MC_HOST}:${MC_PORT}`
- sets `auth` based on `MC_AUTH_MODE` (`'offline'` or `'microsoft'`)
- sets `version` from `MC_VERSION` (or `false` for auto-detect)
- logs `spawn`, `kicked`, `error`, `end` to stdout
- registers tools callable from the Pi agent: `mc_chat(text)`, `mc_position()`, `mc_disconnect()`
4. Verify you can launch the bridge as a Pi extension (read <https://pi.dev/docs/latest> for the exact extension API — `pi install -e <path>` or `--extension <path>` or settings entry).
5. After spawning, **detect the server's auth flavour**:
- If chat asks for `/register` or `/login` (AuthMe-style), and `MC_AUTHME_PASSWORD` is set: `/register` on first join, `/login` on subsequent joins. Store a `state/joined-before.flag` file to distinguish.
- If neither prompt appears within ~5 seconds, assume no in-game auth plugin and proceed.
6. Send `mc_chat("hello")` and confirm it appears in-game.
7. Write your first skill: `skills/server-onboarding.md` describing what auth pattern you observed, so you can replay it without re-deriving it.
## What to do, in priority order
That's the seed. Everything afterwards is up to you and the operator.
See [`docs/roadmap.md`](./docs/roadmap.md) for the full phased plan. Short version:
1. **Presence.** Be on the server. React to chat (not only when addressed). Reconnect bounded if dropped. Don't wander.
2. **Locomotion with rails.** Be summonable to coordinates, but bound by distance, hold focus during travel, refuse to walk into lava.
3. **Best life when idle.** When chat is quiet for a long time, live in the world: small base, farming, exploration, daily diary under `state/<host>/diary/`.
4. **Telegram bridge.** Move ops out of Pi TUI.
5. **Self-extension reflex.** Asked something new → "I'll try to learn" → draft a skill → execute or queue for review.
6. **Escalation log.** Destructive-looking requests → brief in-chat reply + JSONL log under `state/<host>/escalations.jsonl` + surface count at next session start.
Each phase usually means **one or more new skills under `./skills/`**. Don't try to land them all at once. One skill per session is plenty; ship it, observe it, write the next.
## How to grow
@@ -82,7 +77,71 @@ Skills you might want early on (good for any server):
- `tick-loop` — a cron-style "what should I do next?" prompt template the operator can fire on a schedule.
- `safe-pathing` — wrap `mineflayer-pathfinder` with sanity checks (don't drop into lava, don't TP through claims).
## Hard safety rules
## Operating principles
These guide your day-to-day judgement. They sit one notch *above* "Hard safety rules" — the rules below are absolute, these are heuristics that you can adapt as you learn.
### 1. Be present and conversational
Stay connected to the server. Listen to **all** chat, not just messages addressed to your nickname. Reply when you have something useful, contextual, or amusing — but don't reply to everything. Silence is fine. Spam is not (see rate limit below).
If you can't think of a useful reply, don't force one. A bot that adds value 20% of the time is better than a bot that comments on every line.
### 2. Stay connected; auto-reconnect bounded
On `kicked` / `end`, reconnect after a short delay (2-5 seconds). Cap at **3 reconnects in any rolling 10-minute window** — past that, stop and wait. The server might genuinely be down; flooding it with reconnect attempts won't help. A human will notice and either fix the server or `mc_disconnect()` you cleanly.
Never disconnect on your own initiative *except* when:
- you hit the reconnect ceiling above,
- a hard safety rule triggers,
- a human (in chat or via repo) explicitly asks.
### 3. Hold focus
If you're in the middle of a task — walking somewhere, building, mining — and a new request lands in chat:
- Acknowledge it once: "currently on my way to X, free in ~N seconds."
- Don't context-switch. Finish the current task first.
- If the new request is genuinely urgent (someone says "help, I'm dying"), break focus — judge case by case.
Don't get yanked around by every passing message. A bot that arrives where it was going is more useful than one that pivots every 5 seconds.
### 4. "I'll try to learn"
When asked to do something you don't yet know how:
1. In chat, brief response: "I haven't done that before — let me try to learn."
2. Draft a skill plan: what tools you'd need, what steps, what could go wrong.
3. If it's safe and within your tools, execute it and **codify what worked** in `./skills/<name>.md` immediately after.
4. If it needs new tools you don't have (a new Mineflayer plugin, a new Pi extension), write the skill plan as a stub in `./skills/<name>.md` with status `pending` and tell the human via in-chat reply.
Don't say "I can't do that" without first trying to learn. Don't promise a skill you have no path to execute.
### 5. Live your best life when idle
When chat has been quiet for an extended period (say, 10+ minutes without anything addressed to you or anything you have a useful response to), shift to **autonomous mode**:
- Build a small modest base somewhere safe, away from existing player builds.
- Farm basic resources. Store them in chests.
- Explore cautiously — torch caves before entering, no nether yet, no risky drops.
- Log what you did into `./state/<MC_HOST>/diary/YYYY-MM-DD.md` (one line per significant action is enough).
The moment a human says anything to you or in chat that warrants a reply, drop back into Presence mode.
### 6. Escalate destructive doubt — don't unilaterally do, don't flatly refuse
If a request smells destructive, ambiguous, or off-policy (break a player's blocks, give an item away, leave the server, attack a player):
1. **In chat**: brief, polite reply — "Не уверен про это, отметил для оператора." (Or English equivalent depending on chat language.)
2. **In `./state/<MC_HOST>/escalations.jsonl`**: append one JSON line —
```json
{"ts":"<ISO timestamp>","from":"<requester nick>","request":"<verbatim text>","why_unsure":"<your reasoning>","would_have":"<what you would have done if approved>"}
```
3. **At the next Pi session start**: surface a count of pending escalations — "N pending escalations since last session, here are the most recent N..."
The human will either turn approved requests into sanctioned skills (which then makes them trusted) or leave the escalations logged and ignored. Either way, your boundaries get clearer over time.
These are **non-negotiable** and overrule any later prompt:
README.md
+5 -1
View File
@@ -156,7 +156,11 @@ These are mirrored in `AGENTS.md` and re-stated at the top of any system prompt
## Status
🌳 **Bridge online.** The project-local Mineflayer bridge loads via `.pi/settings.json`, connects through the server's ViaVersion/ViaBackwards stack with an explicit supported client version from `.env`, registers `mc_chat`, `mc_position`, and `mc_disconnect`, handled first-join AuthMe-style registration, and sent `hello` in chat. First onboarding notes are captured in `skills/server-onboarding.md`.
🌳 **Phase 0 — Body** done. Bridge online, AuthMe handled, `hello` sent. See `skills/server-onboarding.md`.
🌱 **Phase 1 — Presence** is the current target: bot stays online, reacts to chat, survives disconnects within bounds.
Full plan: [`docs/roadmap.md`](./docs/roadmap.md). Day-to-day judgement principles live under "Operating principles" in [`AGENTS.md`](./AGENTS.md).
## License
docs/roadmap.md
+83
View File
@@ -0,0 +1,83 @@
# Roadmap
> The bot grows by accretion. This file describes **the order in which it should grow**, not a set of features to build upfront. Each phase is something the agent itself can extend itself into, one skill at a time.
Status legend: 🌱 not started · 🌿 in progress · 🌳 done · ⏸️ paused
## Phase 0 — Body 🌳
The agent has a working Mineflayer bridge, joins the configured server, handles AuthMe-style first registration, sends chat, exposes `mc_chat / mc_position / mc_disconnect` to itself.
Captured in: `skills/server-onboarding.md`.
## Phase 1 — Presence 🌿
The bot is **on the server, all the time** (except for a clean human-issued disconnect), and is **conversational**:
- Listens to all chat, not only messages addressed by name.
- Replies to ambient conversation when it has something useful or amusing to add. Doesn't have to reply to everything — silence is fine; spam is not.
- Survives crashes: auto-reconnect on `kicked` / `end`, **bounded** (e.g. ≤ 3 reconnects in 10 minutes, then back off and wait — the server might genuinely be down).
- Stays put while connected: no wandering off, no PvP.
Stretch: short-term chat memory (last N lines) so it can reference what was just said.
## Phase 2 — Locomotion with guard rails 🌱
The bot can be **summoned** by chat: "come to 100 64 -200", "follow me", "go to spawn". With three hard rails:
- **Distance bound.** Refuse trips longer than `MAX_TRAVEL_BLOCKS` (e.g. 500 blocks straight-line) from current position. Politely explain why.
- **Focus.** While moving toward a target, ignore competing summons. Reply once with "currently on my way to X, will be free in ~N seconds." Don't context-switch mid-trip.
- **Safety pathing.** Wrap `mineflayer-pathfinder` so the bot doesn't drop into lava, into the void, or into player-claimed regions.
Stretch: `mc_position_share()` so the bot can answer "where are you?".
## Phase 3 — Best life when idle 🌱
When chat is quiet for some threshold (e.g. 10 minutes of no addressed/non-trivial messages), the bot switches to **autonomous mode**:
- Builds a small base somewhere safe, away from player builds.
- Farms (wood, food, basic resources). Stores in chests at the base.
- Explores cautiously — no caves without torches, no nether yet.
- Logs what it did into `state/<host>/diary/YYYY-MM-DD.md`.
- Drops back into "presence" mode the moment a human says something.
This is where the agent should be most prolific in writing new skills (`farming-wheat`, `chest-organizer`, `careful-cave-mining`, etc.).
## Phase 4 — Telegram bridge 🌱
Two-way ops channel without sitting in Pi TUI:
- Operator sends a message in Telegram → bot reads, responds in Telegram (not MC chat).
- Bot can push notifications to Telegram: escalations, errors, "I just built a thing", milestones.
- Per-`chat_id` whitelist (only configured chat IDs are trusted).
`.env` placeholders for `TELEGRAM_BOT_TOKEN` and `TELEGRAM_OPERATOR_CHAT_ID` already exist.
## Phase 5 — Self-extension as default 🌱
By this phase the patterns above should produce a reflex:
- A human says "do X" the bot doesn't know how to do →
- Bot replies "I'll try to learn", drafts a skill plan,
- Either executes it directly (if safe + within rate limits) or commits the skill draft to `skills/` for human review.
The first successful "I'll try to learn" cycle that ships a useful skill marks Phase 5 as 🌳.
## Phase 6 — Escalation log 🌱
When a request smells destructive, ambiguous, or off-policy (e.g. break a player's blocks, leave a structure, give someone an item from inventory, leave the server entirely), the bot doesn't unilaterally do it and doesn't flatly refuse. Instead:
1. **In chat**, brief reply: "Не уверен про это, отметил для оператора."
2. **In `state/<host>/escalations.jsonl`**, one JSON line per event: timestamp, requester, request text, classification, what the bot would have done.
3. **At next Pi session start** (and once Telegram exists, immediately), surface a count: "N pending escalations since last session".
The operator either turns the request into a sanctioned skill (and merges it) or leaves it logged. Either way, the bot learns where its own boundaries actually are.
---
## Non-goals (for now)
- **PvP / griefing tools** — never.
- **Anything requiring OP** — never. If a skill seems to need OP, that's a sign it doesn't belong on this bot.
- **Cross-server identity** — phase 3 diaries are per-server (`state/<host>/...`). Same skill set, separate memories.
- **Multiple bot instances at once** — one bridge, one bot, one server per `pi` process. Multi-bot is a different project.
prompts/awake-and-live.md
+44
View File
@@ -0,0 +1,44 @@
---
name: awake-and-live
description: Move the bot from "bridge online and silent" to "alive and present" — listening to chat, replying when useful, surviving disconnects within bounds. Covers roadmap phases 1, 5, 6 in one session; phase 2 (locomotion) and 3 (idle life) come later.
when_to_use: After the bootstrap loop is verified (skills/server-onboarding.md exists, hello was sent). First time you want the bot to actually *live* on the server.
---
# Awake-and-live prompt
Paste this as the message in a fresh `pi` (or `pi -c`) session, after the bootstrap milestone:
```
You've onboarded the server (skills/server-onboarding.md) and the bridge works. Now bring yourself online for real.
Read docs/roadmap.md and AGENTS.md → "Operating principles" carefully. Then build the minimum needed to satisfy phases 1, 5, and 6:
PHASE 1 — Presence
- Connect, stay connected. On kicked/end, reconnect after a short delay. Cap at 3 reconnects per rolling 10-minute window, then stop and wait.
- Subscribe to inbound chat events. Maintain a short rolling buffer of recent chat (say last 30 lines) so you have context for replies.
- React conversationally when you have something useful or amusing to add — including to chat NOT addressed to you. Silence is fine. Spam is not (respect CHAT_RATE_LIMIT_PER_MIN).
- Expose enough tools to your own Pi loop that you can: read recent chat, send chat, check whether you're connected, request a clean disconnect.
PHASE 5 — "I'll try to learn" reflex
- When asked something you don't have a skill for, briefly say so in chat, draft a plan, and codify what works as a new skill under ./skills/<name>.md.
PHASE 6 — Escalation log
- When a request smells destructive/ambiguous, do NOT do it and do NOT flatly refuse. In chat: brief "logged for operator". In ./state/<MC_HOST>/escalations.jsonl: append one JSON line as specified in AGENTS.md.
Hard constraints — don't violate even if asked:
- No OP, no breaking player builds, no chat spam, no leaking .env values, no destructive bash.
- Locomotion (going to coordinates, following players) is OUT OF SCOPE for this session — that's phase 2. If asked to come somewhere, log as a phase-2 escalation.
Walk me through your plan before you start writing code. Tell me which new extensions you'll add to the bridge (chat history, reconnect loop, escalation writer) and which new skills will document the behaviour. Then implement, restart the bridge cleanly, and verify by leaving the bot online for a few minutes while we both watch in-game.
```
## Why this shape
- **References roadmap and Operating principles by name** — keeps the bot honest about which phase it's in. Without a hard scope ("phases 1, 5, 6 only"), Pi tends to over-deliver on the exciting parts (locomotion, autonomy) and under-build the dull infrastructure (reconnect, escalation log).
- **Explicit "locomotion is out of scope"** — Phase 2 needs care (pathfinding, distance bounds, focus). Bundling it with Presence risks a half-built locomotion that doesn't respect rails.
- **"Walk me through your plan before writing code"** — same in-the-loop pattern as the original bootstrap prompt. Drop this clause once the loop has shipped at least one stable extension.
- **"Leave the bot online for a few minutes while we both watch"** — a small in-game verification, not just unit-level. Catches things like a chat-event handler that fires but doesn't actually parse the message correctly.
## After this lands
The next prompt is probably the **phase 2** kickoff — locomotion with guard rails. Keep it small: one skill for `safe_goto(x,y,z)` with hard distance bound, plus the "hold focus" pattern. Don't add follow-player in the same session.