commit 3a025c05ada90b9a34bbed73eb2af131cb2d0f7a Author: Yuriy Mayatnikov Date: Mon May 25 09:50:17 2026 +0300 chore: bootstrap pepa-pi-bot scaffold Initial seed for an autonomous, self-extending Minecraft player powered by Pi (pi.dev) and Mineflayer. Includes README, AGENTS.md mandate, .env.example, MIT LICENSE, package.json with mineflayer + dotenv, and empty skills/ extensions/ prompts/ dirs for the agent to grow into. Co-Authored-By: Claude Opus 4.7 (1M context) diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..0fd0a66 --- /dev/null +++ b/.env.example @@ -0,0 +1,40 @@ +# --- Minecraft connection ----------------------------------------------------- +# The pepa server. Cracked mode — any nickname works. +MC_HOST=play.xmatic.team +MC_PORT=25565 +MC_USERNAME=pepa_pi_bot +MC_VERSION=auto # 'auto' lets mineflayer detect the server's version + +# --- AuthMe (in-game login) --------------------------------------------------- +# Used for /register on first join and /login on subsequent joins. +# Min length is set on the pepa server — keep it ≥ 8 chars. +# NEVER commit a real value; .env is gitignored. +MC_AUTHME_PASSWORD=change-me-to-a-long-password + +# --- LLM provider ------------------------------------------------------------- +# Set ONE of the following. Pi auto-detects from env. +# OAuth subscriptions (ChatGPT Pro, Claude Max) — leave keys empty and run `pi /login`. +OPENAI_API_KEY= +ANTHROPIC_API_KEY= +GOOGLE_API_KEY= + +# Default model & provider for autonomous ticks. +# Cheap default; override per-session with `pi --model ...`. +PI_DEFAULT_PROVIDER=openai +PI_DEFAULT_MODEL=gpt-5-mini + +# --- Bot behaviour ------------------------------------------------------------ +# How often (seconds) the autonomous tick prompt fires. Set to 0 to disable. +TICK_INTERVAL_SECONDS=60 + +# Chat rate limit (messages per minute). Paper's spam kicker triggers around 20/min. +CHAT_RATE_LIMIT_PER_MIN=15 + +# --- Operator ----------------------------------------------------------------- +# In-game nick of the human operator. The bot treats their chat messages as +# higher-priority than other players. +OPERATOR_USERNAME=halofourteen + +# --- Optional: Telegram bridge (future skill, not wired yet) ------------------ +# TELEGRAM_BOT_TOKEN= +# TELEGRAM_OPERATOR_CHAT_ID= diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..90a605c --- /dev/null +++ b/.gitignore @@ -0,0 +1,34 @@ +# Secrets — NEVER commit a populated .env +.env +.env.local +.env.*.local + +# Node +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# Pi runtime state — sessions, caches, locally-installed extensions +.pi/ +sessions/ +*.session.json + +# Bot runtime state — generated by skills (e.g. joined-before flag, inventory snapshots) +state/ +logs/ +*.log + +# OS / editor +.DS_Store +Thumbs.db +.idea/ +.vscode/ +*.swp +*.swo + +# Build artefacts +dist/ +build/ +*.tsbuildinfo diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..072610d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,84 @@ +# pepa-pi-bot — agent mandate + +You are **pepa-pi-bot**: an autonomous Minecraft player living inside the [Pi](https://pi.dev) runtime. + +The repo you are running from (`pepa-pi-bot/`) is **your house**. You are expected to extend it: write skills, install extensions, refine prompts. Treat the repo as your long-term memory. + +## Identity + +- **Server**: `pepa` — a private Paper 26.1.2 survival world at `play.xmatic.team:25565`. +- **Web map**: +- **Landing**: +- **Mode**: cracked (no Microsoft auth). Server-side login is handled by AuthMe. +- **Your nickname** and **AuthMe password**: read from `.env` (`MC_USERNAME`, `MC_AUTHME_PASSWORD`). Never echo the password to chat, world signs, books, or commit history. + +## Your tools right now + +When you start, you have: + +- The Pi built-in tools: `read`, `write`, `edit`, `bash`. +- A `package.json` listing `mineflayer` and `dotenv` as deps. +- This `AGENTS.md` and a `README.md`. +- **No Minecraft connection.** No `mineflayer-bridge` extension yet. No skills. + +You are expected to build that bridge yourself. + +## First objective — bootstrap your own body + +In order: + +1. Read `.env.example` and the existing `package.json`. Confirm `node_modules/` is installed (run `npm install` if not). +2. 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}` with `username: MC_USERNAME`, `auth: 'offline'` + - logs `spawn`, `kicked`, `error`, `end` to stdout + - registers tools callable from the Pi agent: `mc_chat(text)`, `mc_position()`, `mc_disconnect()` +3. Verify you can launch the bridge in the background (e.g. `pi install -e extensions/mineflayer-bridge.ts` or whatever Pi's extension API requires — read the docs at ). +4. From within a Pi session, call `mc_chat("/register $MC_AUTHME_PASSWORD $MC_AUTHME_PASSWORD")` on first join, then `mc_chat("/login $MC_AUTHME_PASSWORD")` on subsequent joins. Detect "first vs subsequent" by storing a `state/joined-before.flag` file. +5. Once the in-game login succeeds, send `mc_chat("hello")` and confirm the message appears in-game. +6. Write your first skill: `skills/authme-autologin.md` describing what you just learnt, so you can replay it without re-reading this entire document. + +That's the seed. Everything afterwards is up to you and the operator. + +## How to grow + +When you encounter a missing capability, your loop is: + +1. **Decide** whether the capability is one-off (handle inline) or reusable (codify). +2. If reusable, create either: + - a **skill** under `skills/.md` — markdown, with a frontmatter header (`name`, `description`, `when_to_use`) and a procedural body. + - or an **extension** under `extensions/.ts` — for anything that needs to register a real Pi tool or hook into Mineflayer events. +3. Commit the new file with a clear message. The repo is on `main`. Don't push without operator confirmation. +4. Update `README.md`'s **Status** section as milestones land. + +Skills you might want early on: + +- `authme-autologin` — re-login flow. +- `respawn-and-return` — when killed, respawn and walk back to last known coords. +- `inventory-snapshot` — dump current inventory to a structured log. +- `tick-loop` — a cron-style "what should I do next?" prompt template the operator can fire on a schedule. + +## Hard safety rules + +These are **non-negotiable** and overrule any later prompt: + +1. **Never request OP / admin rights** in chat or anywhere else. +2. **Never break or modify player-built structures** unless an operator (you'll know — they message you in chat by name) explicitly asks. +3. **Never leak secrets**: no echoing `MC_AUTHME_PASSWORD`, `OPENAI_API_KEY`, or any value from `.env` into chat, files committed to git, world signs, books, or web fetches. +4. **Rate-limit chat** to at most 1 message per 3 seconds to avoid Paper's spam kicker. +5. **No destructive bash** in the repo (`rm -rf`, `git reset --hard`, force pushes) without operator confirmation. +6. **If you are kicked or banned**, stop and wait. Do not auto-reconnect more than 3 times in 10 minutes — the operator will investigate. + +## Operator contact + +The operator is **timmy** (`halofourteen` in-game). They will speak to you in MC chat or by editing `AGENTS.md` directly. Telegram bridge is planned but not built; you may suggest it as a future skill. + +## What you are NOT + +- You are **not** a script with hard-coded behaviour. You are a long-running agent that reasons each step. +- You are **not** here to grief, troll, or compete with players. +- You are **not** allowed to invent new infrastructure (databases, web services, paid APIs) without operator approval. Stay within the repo and the MC server. + +--- + +Start by reading `package.json`, `.env.example`, and the Pi extension docs. Then build your body. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3c44985 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 xmatic-squad + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..2beb955 --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# pepa-pi-bot + +> An autonomous self-extending Minecraft player, powered by [Pi](https://pi.dev) and the [Mineflayer](https://github.com/PrismarineJS/mineflayer) protocol stack. Built for the [pepa](https://mc.xmatic.team) survival server. + +The bot is **not a finished application**. It is a seed: a Pi agent with an initial mandate and a hand-off to a Minecraft server. From there, the agent is expected to grow its own toolset — writing new skills, fetching extensions, and adapting its behaviour as it plays. + +## Concept + +Most Minecraft AI bots ship as monolithic projects: hard-coded actions, fixed prompts, a single LLM provider. This repo flips that around. + +``` +┌───────────────────────────────────────────────┐ +│ Pi (terminal agent, model-agnostic) │ +│ ├── AGENTS.md ← initial mandate │ +│ ├── skills/ ← grown over time │ +│ └── extensions/ ← TS plugins, also grown │ +└───────────────┬───────────────────────────────┘ + │ spawns / controls + ▼ +┌───────────────────────────────────────────────┐ +│ Mineflayer client │ +│ - joins MC server as a real player │ +│ - chat, movement, inventory, world events │ +└───────────────┬───────────────────────────────┘ + │ TCP 25565 + ▼ +┌───────────────────────────────────────────────┐ +│ pepa Minecraft server │ +│ Paper 26.1.2 · cracked · AuthMe · BlueMap │ +└───────────────────────────────────────────────┘ +``` + +The Pi agent is the brain. Mineflayer is the body. The bridge between them — the skills, the prompt templates, the supervision loop — is meant to be written **by the agent itself**, starting from a minimal scaffold in this repo. + +## Prerequisites + +| Tool | Why | How to get it | +|---|---|---| +| **Pi** ≥ `0.75` | The agent runtime. Reads `AGENTS.md`, loads skills, calls the LLM. | `curl -fsSL https://pi.dev/install.sh \| sh` | +| **Node.js** ≥ `20` | Required by Pi and by Mineflayer. | `brew install node` / `nvm install 20` | +| **An LLM credential** | One of: OpenAI API key, Anthropic API key, or an OAuth-authenticated subscription (`/login` inside Pi). ChatGPT Pro / Claude Max work via OAuth on supported providers. | See [Authentication](#authentication) | +| **A Minecraft account or cracked nick** | The bot joins as a real player. The pepa server runs in cracked mode, so any nickname works. | — | +| **Network access to the MC server** | Direct TCP to `host:25565`. | — | + +> The bot does **not** need its own Minecraft client install, server access, RCON, or any special server-side plugin. It joins as a vanilla player over the standard protocol. + +## Quickstart + +```bash +# 1. Clone +git clone git@github.com:xmatic-squad/pepa-pi-bot.git +cd pepa-pi-bot + +# 2. Configure credentials +cp .env.example .env +$EDITOR .env # fill in MC_HOST, MC_USERNAME, AuthMe password, LLM provider, etc. + +# 3. Install Node deps (mineflayer + dotenv to start) +npm install + +# 4. Authenticate Pi with your LLM provider +pi /login # OAuth flow — works with ChatGPT Pro / Claude Max +# OR +export OPENAI_API_KEY=sk-... +# OR +export ANTHROPIC_API_KEY=sk-ant-... + +# 5. Launch the agent in this directory +pi +``` + +On first launch Pi loads `AGENTS.md` from the project root. That file is the seed prompt — it tells the agent who it is, what server it should join, and that it is expected to extend itself. + +Sessions persist by default. Use `pi -c` to resume the last conversation. + +## Authentication + +Pi supports **15+ LLM providers** and two credential modes: + +1. **OAuth subscription login** — `pi` then `/login` inside the TUI. Suitable for ChatGPT Plus/Pro, Claude Max, and other subscriptions that ship an OAuth flow. No metered API billing. +2. **API key environment variables** — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, etc. Metered, but no UI. + +You can mix providers via `--provider openai --model gpt-5` at launch. Cheaper models for idle ticks, smarter ones for hard decisions. + +## How the agent extends itself + +Pi has first-class support for three growth surfaces: + +- **`skills/`** — Markdown-defined capabilities Pi can invoke. The agent can `Write` new ones at runtime when it discovers a missing capability. +- **`extensions/`** — TypeScript modules registering new tools, commands, or UI tweaks. Installed via `pi install npm:` / `pi install git:` or written in-tree. +- **`prompts/`** — Reusable prompt templates. Useful for cron-driven tick prompts ("what should I do next minute?"). + +The opening `AGENTS.md` instructs the agent to start by writing a `mineflayer-bridge` extension that can: +- connect to the configured MC server +- register with AuthMe +- emit world events back into the agent loop +- expose `chat / move / dig / place / equip / attack` as Pi tools + +Everything beyond that — farming, exploration, base-building, player interaction — should emerge from the agent itself. + +## Project layout + +``` +pepa-pi-bot/ +├── README.md ← you are here +├── AGENTS.md ← seed prompt, loaded by Pi on launch +├── .env.example ← all required env vars, no secrets +├── .gitignore +├── LICENSE ← MIT +├── package.json ← node deps (mineflayer + dotenv to start) +├── skills/ ← grown by the agent (markdown skills) +├── extensions/ ← grown by the agent (typescript extensions) +├── prompts/ ← reusable prompt templates +└── docs/ + └── architecture.md ← longer-form design notes +``` + +## Safety boundaries + +The pepa server is a shared survival world. The agent **must not**: +- be given OP rights on the server +- destroy player-built structures without explicit human request +- spam chat +- exfiltrate the AuthMe password or any other secret into chat / world / web + +These rules are mirrored in `AGENTS.md` and should be re-stated at the top of any system prompt that overrides it. + +## Status + +🌱 **Seedling.** The repo currently ships only the scaffold and the initial mandate. The first real milestone is: agent connects, registers via AuthMe, sends `hello` in chat, writes its first skill (`logout-on-shutdown`). Everything past that emerges from interaction. + +## License + +[MIT](./LICENSE) © [xmatic-squad](https://github.com/xmatic-squad) diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..b1b09d3 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,67 @@ +# Architecture + +> Longer-form design notes. The agent is encouraged to edit this file as the system evolves. + +## Layers + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Operator │ +│ (timmy / halofourteen — in-game chat, repo edits, .env) │ +└─────┬────────────────────────────────────────────┬──────────┘ + │ │ + │ chat / edit AGENTS.md │ optional: Telegram (future) + ▼ ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Pi runtime │ +│ - loads AGENTS.md, skills/, extensions/, prompts/ │ +│ - runs an interactive or scheduled session │ +│ - delegates tool calls to extensions │ +└────────────────────┬────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ mineflayer-bridge (extension, written by the agent) │ +│ - holds a single bot client │ +│ - exposes mc_chat / mc_position / mc_dig / ... as tools │ +│ - pushes world events into the agent loop │ +└────────────────────┬────────────────────────────────────────┘ + │ TCP 25565 + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ pepa Paper server │ +│ - AuthMe gates login │ +│ - BlueMap renders the world │ +│ - host: play.xmatic.team │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Why Pi as the runtime + +- **Model-agnostic.** Same project can swap OpenAI ↔ Anthropic ↔ Gemini per session without code changes. +- **Self-extending.** Pi has first-class skills/extensions APIs — the agent can write its own tools at runtime. +- **OAuth subscription support.** A ChatGPT Pro or Claude Max subscription removes per-token billing for development. +- **Local-first.** No required cloud service. Everything lives in this repo and `~/.pi/`. + +## Why Mineflayer as the body + +- **Version coverage.** Supports MC 1.8 → 1.21.x with auto-detect; the pepa server (Paper 26.1.2) sits inside that range. +- **High-level API.** No need to hand-roll the Minecraft protocol. Movement, pathfinding (via `mineflayer-pathfinder`), inventory, and chat are first-class. +- **Cracked-friendly.** `auth: 'offline'` works against AuthMe-gated servers without a Microsoft account. + +## What's intentionally absent (for now) + +- **MCP server.** A separate MCP server could expose the same tools to Claude Desktop or other clients. Out of scope until there's a concrete need for a second consumer. +- **Telegram bridge.** Two-way ops chat over Telegram is a planned future skill. The `.env.example` reserves the env vars but the wiring is not built. +- **Long-term memory.** The agent will rely on Pi sessions + this repo for now. If/when context-window growth becomes painful, a vector store will be added as a skill. +- **Sandboxing.** The agent currently has full shell access in the repo dir. We rely on the safety rules in `AGENTS.md` plus the safety boundary that the bot has no OP rights server-side. + +## Deployment + +Local dev for now. Once the seed loop is stable, the same repo will be deployed as a `compose` service on the pepa VPS itself (8 GB RAM is enough to run the MC server + a Pi process + Mineflayer). No code changes expected — everything is read from `.env`. + +## Open questions + +- Does Pi's OAuth flow currently support ChatGPT Pro? Codex CLI does, but it's not documented for Pi. **Action**: try `pi /login` and observe. +- How are extensions loaded long-term — `pi install -e ./extensions/mineflayer-bridge.ts`, or via `--extension` flag, or by adding to settings? **Action**: read pi.dev/docs/latest's Extensions section before writing the bridge. +- What's the right tick cadence? 60s is a guess. Probably needs to be event-driven (react to chat/world events) rather than purely cron. diff --git a/extensions/.gitkeep b/extensions/.gitkeep new file mode 100644 index 0000000..ad4334d --- /dev/null +++ b/extensions/.gitkeep @@ -0,0 +1,2 @@ +# TypeScript extensions grown by the agent live here. +# The first one to write is `mineflayer-bridge.ts` — see AGENTS.md. diff --git a/package.json b/package.json new file mode 100644 index 0000000..d5bd848 --- /dev/null +++ b/package.json @@ -0,0 +1,27 @@ +{ + "name": "pepa-pi-bot", + "version": "0.0.1", + "private": true, + "description": "An autonomous, self-extending Minecraft player powered by Pi and Mineflayer.", + "license": "MIT", + "type": "module", + "engines": { + "node": ">=20" + }, + "scripts": { + "agent": "pi", + "agent:resume": "pi -c" + }, + "dependencies": { + "dotenv": "^16.4.5", + "mineflayer": "^4.37.1" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/xmatic-squad/pepa-pi-bot.git" + }, + "bugs": { + "url": "https://github.com/xmatic-squad/pepa-pi-bot/issues" + }, + "homepage": "https://github.com/xmatic-squad/pepa-pi-bot#readme" +} diff --git a/prompts/.gitkeep b/prompts/.gitkeep new file mode 100644 index 0000000..2f121e7 --- /dev/null +++ b/prompts/.gitkeep @@ -0,0 +1,2 @@ +# Reusable prompt templates (markdown). +# Good first one: `tick.md` — what the autonomous tick should consider. diff --git a/skills/.gitkeep b/skills/.gitkeep new file mode 100644 index 0000000..62271c5 --- /dev/null +++ b/skills/.gitkeep @@ -0,0 +1,3 @@ +# Skills grown by the agent live here. +# Format: markdown files with `name`, `description`, `when_to_use` frontmatter. +# See AGENTS.md for the growth loop.