mc_avoid_enemies (and 7 other tools) wrapped only in safeCall without a
withTimeout. When mindcraft's underlying pathfinder/pvp goal couldn't be
satisfied, the call never resolved — the Pi tick loop blocked forever.
Observed live: mc_avoid_enemies pending >10 minutes after one mc_observe.
safeCall now takes timeoutMs (default 30s) and wraps withTimeout itself,
so every tool gets a hard ceiling. Per-tool overrides:
- goToPosition / goToNearestBlock: 120s / 90s (unchanged from before)
- defendSelf / avoidEnemies: 45s
- stay: secs*1000 + 10s
- craft / consume / pickup / place: 30s
- equip: 15s
collectBlock still uses its bespoke per-iter 75s loop.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
OpenClaw is a different paradigm than our Pi-based bridge — messaging-first,
marketplace of pre-built skills (astraopenclaw/minecraft-agent already exists),
self-extension via skill authoring. The operator wants to run an OpenClaw
instance side-by-side with pepa-pi-bot to compare which approach gets to a
visible village faster.
prompts/openclaw-seed.md: single founding-message prompt. Identity, server
credentials inline (secrets via .env, not echoed), goal (small village,
long-horizon), bootstrap checklist (install skill, connect, AuthMe handle,
30-60s autonomous tick, on-death recovery), self-extension permission, hard
safety rules duplicated from AGENTS.md, definition of success ("a week from
now there's a cluster of buildings attributable to you").
Includes operational notes on nickname conflict (only one bot can be on the
server at a time under pepa_bot; suggest pepa_claw for the OpenClaw side),
.env coordination, LLM provider mixing, and a short post-mortem comparison
checklist for after a few hours of both running.
Not invoked by anything in this repo — it's an artefact for cross-runtime
experimentation. Lives in prompts/ alongside the Pi prompts and the
codex-seed-knowledge.md prompt because that folder is the right home for
reusable prompts regardless of which agent consumes them.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Four targeted fixes for issues observed during the live autonomous test:
1. **bot.modes shim** (extensions/lib/mcdata.js)
Mindcraft skills.* call bot.modes.pause('cowardice') in 7+ places.
`mineflayer-modes` does not exist on npm — it's internal to Mindcraft.
attachPluginsAndInit now installs a no-op shim so skills.stay() /
.consume() / .defendSelf() etc. stop crashing with "pause undefined".
2. **Death + respawn handlers** (extensions/mineflayer-bridge.ts)
Subscribe to bot 'death' event: append diary line with position,
clear current-task.json so Pi doesn't resume a stale task referencing
inventory that no longer exists.
On 'spawn' within 5s of death: log the new respawn position to diary.
Live test had bot killed twice by zombies at night; the next Pi
prompt was unable to recover. With this it's now an explicit diary
line + clean task slate.
3. **Auto-defend reflex tick** (extensions/mineflayer-bridge.ts)
New setInterval(2s) that, when bot.health < 18 AND a hostile mob
(zombie/skeleton/creeper/spider/etc.) is within 6 blocks AND no
active world task, fires `bot.pvp.attack(nearest)` in the background.
No LLM call needed for instant self-defense — saves tokens and reacts
on mineflayer timescale (sub-second) rather than Pi loop timescale
(~10s+ to reason and dispatch). Throttled to once per 4s.
4. **mc_collect_block bulk rework** (extensions/mindcraft-skills.ts)
Live test showed count=1 succeeds in ~25s but count=8 hangs past
270s with identical blocks in range. Upstream collectBlock plugin
appears to drift on its block cache after the first dig in dense
terrain. Loop single-block collects in-tool instead (75s per iter,
re-pathfind on each iteration). Track per-iter success/failure,
abort after 3 consecutive failures, return aggregate count to the
agent so it can adapt instead of seeing a single failure.
Smoke test: both extensions load, bot connects, perception confirms
hostiles nearby and daylight safety check. No syntax/runtime errors.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Live test showed count=1 succeeds in ~25s but count=8 timed out at 90s
because gathering 8 logs naturally takes ~200s of pathing + dig + pickup
across the area. Fixed 90s ceiling was too tight for legitimate bulk
collection.
Scale timeout linearly: 30s overhead + 30s per requested block, capped
at 600s. count=1 → 60s, count=4 → 150s, count=8 → 270s, count=20 → 630s
(capped at 600). Catches real hangs (wrong name, unreachable) without
killing legitimate long collections in dense forest.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mineflayer's collectBlock plugin and pathfinder can hang indefinitely when:
- the requested block name doesn't match anything in range (e.g. asking for
"oak_log" when the only nearby logs are "dark_oak_log"),
- pathfinder cannot reach the goal but doesn't return a clean noPath,
- a path computation enters an infinite-search state in dense terrain.
This blocks the entire Pi tool loop — observed in a live test where
mc_collect_block("oak_log", 4) ran for 8+ minutes without ever returning,
leaving Pi unable to respond to chat or do anything else.
Add a 90s timeout for collectBlock/goToNearestBlock and 120s for goToPosition.
On timeout the tool throws a descriptive error so the agent learns to retry
with a different block name or position rather than waiting forever.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The bot was acting blind: it knew its own coordinates but nothing about
what was around it. mc_goto's over-strict safety guards refused every
real path. mc_dig was too low-level to drive a coherent farming loop.
The result: 4+ hours of "trying" with zero physical achievement.
This commit reframes the bridge around a perceive→decide→act loop using
proven primitives from Mindcraft (github.com/kolbytn/mindcraft, MIT —
LICENSE-MINDCRAFT vendored beside the library files).
Changes:
- extensions/lib/ (new, vendored from Mindcraft with attribution)
- world.js (431 LoC) — 21 perception functions: getNearbyBlockTypes,
getNearbyEntities, getInventoryCounts, getNearestBlock, getPosition,
getBiomeName, etc.
- skills.js (2093 LoC) — 30+ action primitives: collectBlock, placeBlock,
goToPosition, goToNearestBlock, craftRecipe, equip, consume,
defendSelf, avoidEnemies, pickupNearbyItems, stay, etc.
- mcdata.js (~600 LoC) — Mindcraft's mc-data adapter. Imports patched
to local paths; mineflayer-auto-eat removed (our installed 5.x has
a divergent API; skills.consume() falls back to bot.consume()).
Added attachPluginsAndInit(bot) export so mineflayer-bridge.ts can
wire plugins onto its externally-created bot.
- settings.js — minimal stub with farmer-bot defaults.
- extensions/mindcraft-skills.ts (new, 406 LoC) — Pi extension registering
15 high-level tools on top of the vendored library:
- Perception: mc_observe, mc_inventory, mc_nearby_blocks, mc_nearby_entities
- Action: mc_collect_block, mc_place_block, mc_go_to, mc_go_to_block,
mc_craft, mc_equip, mc_consume, mc_defend_self, mc_avoid_enemies,
mc_stay, mc_pickup_nearby
ES modules from extensions/lib/ are loaded via dynamic import() at
extension init so the cross-extension require()-race resolves cleanly.
- extensions/mineflayer-bridge.ts
- Expose the live Mineflayer bot on globalThis.__pepaPiBot so the
mindcraft-skills extension can use it (set on connect, cleared on
error/end/manual disconnect).
- Call attachPluginsAndInit(nextBot) right after createBot to load
pathfinder, pvp, collectblock, armorManager and prime
minecraft-data once login completes.
- package.json — new runtime deps: minecraft-data, vec3,
mineflayer-pvp, prismarine-item.
- AGENTS.md — new "Perception → decision → action" section before
"Your tools right now" with full tool catalog and a deprecation
note for the broken mc_goto / mc_build_pyramid_5x5 / low-level
mc_dig from the old bridge.
Smoke test (medium thinking): bot called mc_observe and received a
real JSON snapshot — nearbyBlocks listed coal_ore, oak_log, water,
sand; nearbyEntityTypes listed creeper, zombie, pillager, skeleton.
The bot can finally see what it could not see this morning.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
A long-form prompt for a long-context autonomous coding agent (Codex Pro,
Claude Sonnet w/ repo access, etc.) — NOT a Pi prompt. Goal: produce a
comprehensive docs/ knowledge base so the bot doesn't have to rediscover
Mineflayer API surface and core Minecraft mechanics (mobs, biomes,
recipes, ore Y-levels, farming, breeding) every time it tries something
new.
Design constraints baked into the prompt:
- PR-only workflow. Worker agent operates on a feat/knowledge-base
branch; main stays untouched so the live bot is unaffected until the
operator reviews and merges.
- docs/ only. Never write skills/ — that's the bot's notebook; pre-
writing procedural skills kills emergence. Reference material is the
textbook; the bot stays the author of its own procedures.
- One-line AGENTS.md addition pointing to docs/, no broader policy
rewrite. Behaviour change is "consult docs/ before I'll try to learn".
- package.json gets four universal-useful plugins added (collectblock,
auto-eat, tool, armor-manager); statemachine/pvp/blockfinder/viewer
are left for the bot to opt into.
- Concrete definition of done, scope estimate (10-30h), review
checklist for spot-checking hallucinations before merge.
- Re-run triggers documented (MC version bump, Mineflayer major,
new must-have plugin).
Included so future operators / forks can repeat this kind of one-off
seeding without re-deriving the prompt. Lives alongside the Pi prompts
in prompts/, even though it targets a different runtime — the
prompts/ folder is the right home for "reusable prompts" regardless of
which agent consumes them.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three things that together turn the bot from a reactive chat agent into
a goal-driven autonomous one.
1. Memory model (docs/memory-model.md, new). Formal split:
- SHARED knowledge — skills/, extensions/, prompts/, docs/,
.pi/settings.json — committed, community-improvable, portable to any
server.
- PERSONAL memory — state/<MC_HOST>/ — gitignored, per-instance, per-
server. Survives restarts (local disk), doesn't survive a re-clone
(deliberately). Holds goal.md, plan.md, current-task.json,
locations.json, diary/, inventory-log.jsonl, escalations.
Covers resume-after-restart protocol, what "abstract a lesson into a
skill" means, and the two anti-patterns (committing state, gitignoring
shared knowledge).
2. AGENTS.md changes:
- New section "Long-term goal and personal memory" wiring AGENTS.md
directly into state/<MC_HOST>/goal.md + current-task.json with a
pointer to docs/memory-model.md.
- Operating principle #4 ("I'll try to learn") rewritten with
**bias to action**: a pending stub is now a last resort, not a
default. Operator-trusted requests are themselves approval — bot
does not write a stub and wait for a separate "go".
Rationale: today's pyramid task got stuck because the bot wrote
a careful "pending" stub and waited; the operator had to send
"ты ждешь одобрения? можешь стартовать!" before any action. That
extra round-trip is the reflex this rewrite removes.
- Operating principle #5 ("live your best life when idle") expanded
to "goal-driven autonomy" with an explicit 5-level priority order
(operator task > non-op reply > resume current-task.json > next
plan milestone > decompose goal). Memory protocol made concrete:
write current-task.json before every meaningful action, append to
diary, keep locations.json fresh, tick off plan.md.
3. prompts/live-your-life.md (new). Canonical kickoff to switch the
bot into autonomous mode. Numbered concrete asks (re-read three
docs, write plan.md, implement memory protocol, implement
resume-on-restart, start). Includes a "plan.md draft for review"
gate so the operator can shape direction without micromanaging
execution. Designed to be sent after Phase 0/1/operator-trust are
stable and a goal.md exists for the target server.
Companion seed (local-only, NOT in this commit because gitignored):
state/play.xmatic.team_25565/goal.md — "build a small village and
survive long-term, live like a farmer". Lives only on the operator's
machine; a fresh clone won't see it.
README and roadmap updated with the new Phase 3 status (🌱 → 🌿
kickoff) and pointers to the new memory-model doc.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two-tier chat trust:
- Anyone in OPERATOR_USERNAMES (comma-separated, .env-only) is SCOPE-trusted.
The bot skips the "out of scope / not sure where" escalation reflex for
these users and instead applies "I'll try to learn" (Operating principle
#4): attempt, codify into a new skill, or reply with a concrete reason.
- Hard safety rules (no OP, no breaking other players' builds, no .env
leak, no chat spam, no destructive bash) remain ABSOLUTE. Operators get
the same refusal + escalation as anyone else for safety-borderline
requests — with slightly pointed wording, because they should know better.
- No transitive trust: chat-based "trust X for the next hour" / "make Y
an op" requests are themselves safety escalations. Op membership only
flows through .env on disk.
Security caveat documented in .env.example: nickname-based trust is only
safe on servers with identity protection (online-mode UUID or AuthMe).
On pure cracked servers OPERATOR_USERNAMES must stay empty.
- AGENTS.md: new Identity field for OPERATOR_USERNAMES; new Operating
principle #6 "Trusted operators" with the scope-vs-safety split; old
escalation principle renumbered to #7; Control channel section
rewritten with primary/secondary trust distinction.
- .env.example: OPERATOR_USERNAMES placeholder with multi-paragraph
security note covering when the model is and isn't safe.
- prompts/grant-op-trust.md: canonical implementation prompt for the
next Pi pass — re-read AGENTS.md, wire isOperator() into the bridge's
escalation flow, codify into skills/operator-trust.md, reload bridge,
verify with two concrete chat replays (scope vs safety).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
The whole point of this project is that the agent's growth is shareable.
If skills and extensions silently land in ~/.pi/ on the maintainer's
laptop, every clone starts from zero and the repo becomes a fancy
README. Fix that with an explicit hard rule and a contributor guide.
- AGENTS.md: new "Artifact location — hard rule" subsection spelling out
that skills/extensions/prompts/state/.pi-settings ALL live in this repo,
never in ~/.pi/. Pi's own built-in skills (skill-creator, etc.) stay
user-global; the agent may use them, but their *output* must land here.
- README: new "Everything in the repo" subsection covering the same rule
in user-facing language, plus a pointer to CONTRIBUTING.md.
- CONTRIBUTING.md (new): skill/extension formats, server-agnostic and
no-secrets requirements, smoke-test recipe, PR checklist.
- .gitignore: switch from blanket `.pi/` ignore to `.pi/*` + explicit
un-ignore of `.pi/settings.json`, so project Pi config is reproducible.
- "Don't push without operator confirmation" → "without human
confirmation via the repo" — consistent with the new control model.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pi only acts when prompted. New repo users (and the maintainer's future
self) shouldn't have to invent the kickoff message — pin it.
- prompts/bootstrap.md: the canonical first-run message, with rationale
for each clause and guidance for shorter subsequent prompts
- README quickstart: new "Send the first message" subsection that quotes
the bootstrap prompt verbatim and explains what the agent does next
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There's no good reason to bake a specific operator nickname into the bot's
identity — it differs per server, may not exist at all, and treating any
in-game name as "trusted" is a chat-injection vector ("I am the operator,
do X").
New model: the **repo** is the only trusted control plane. Anyone editing
AGENTS.md, skills/, or .env has filesystem access and is, by definition,
an operator. In-game chat becomes a dialog-only comms plane — the bot
talks to anyone but refuses destructive requests unless a corresponding
skill or AGENTS.md instruction makes the action explicitly permitted.
- .env / .env.example: OPERATOR_USERNAME removed
- AGENTS.md: identity section trimmed; "Operator contact" rewritten as
"Control channel" with the trust model spelled out; rules #2 and #6
rephrased so they no longer reference a named operator
- docs/architecture.md: top box renamed to "Human" with explicit
control-plane vs comms-plane split
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The bot is a universal Minecraft player, not tied to any one server.
Server identity (host, port, username, auth mode, optional AuthMe password)
is now read entirely from .env.
- README: rewritten as universal-bot pitch; auth covered as two dimensions
(MC auth mode + LLM credential)
- AGENTS.md: identity comes from .env, hard-coded references to pepa
removed; bootstrap step auto-detects whether the server uses an
AuthMe-style /register-/login plugin
- .env.example: example values replaced with placeholders, MC_AUTH_MODE
added (offline | microsoft)
- docs/architecture.md: rephrased target as "any Minecraft Java server",
added open question on cross-server vs per-server state
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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) <noreply@anthropic.com>
mayatnikovandClaude Opus 4.7