# REPL Self-Evolution Roadmap (Discussion Draft)

## Goal

Turn the current JS planner REPL into a "poor man's coding agent" environment that can:

1. Inspect its own runtime and project code.
2. Read docs (especially Mineflayer docs) from within the REPL.
3. Propose and eventually apply tool/runtime improvements safely.
4. Register event hooks and optional background daemons for long-lived behaviors.

No implementation details in this draft are final; this is a planning artifact for review.

---

## Design Principles

- **Safety-first by default**: proposal mode before apply mode.
- **Auditability**: every introspection and mutation action is logged and replayable.
- **Layered capabilities**: observation -> proposal -> gated execution.
- **Deterministic core loop**: keep turn-based planner behavior stable.
- **Minimal trusted surface**: expose small, explicit APIs rather than raw Node/system access.

---

## Capability Areas

## 1) Self-Introspection Interface (REPL APIs)

Expose a read-oriented introspection namespace in REPL globals.

Proposed APIs:

- `introspect.runtime()` -> model, tool list, limits, feature flags, queue status.
- `introspect.tools()` -> current action/tool signatures and schemas.
- `introspect.memory()` -> mem summary + size stats.
- `introspect.last()` -> previous script/action results.
- `introspect.health()` -> basic diagnostics (event lag, retries, failures).

Notes:

- Start read-only.
- Keep outputs compact and structured.

## 2) Project Code Reading Interface

Expose controlled repository browsing from REPL without full shell.

Proposed APIs:

- `repo.list(path = ".", opts?)` -> file/dir listing (allowlisted roots).
- `repo.read(path, opts?)` -> file snippet with line ranges and size cap.
- `repo.search(query, opts?)` -> ripgrep-backed search with result caps.
- `repo.symbol(path, name)` -> optional simple symbol lookup (later phase).

Guardrails:

- Read-only initially.
- Max file size / line range limits.
- Block secrets and ignored paths (`.env`, keys, tokens, node_modules, build outputs).

## 3) Mineflayer Knowledge Surface

Provide docs/refs to help the agent compose better behavior/tool proposals.

Options:

- Local curated docs bundle (recommended for deterministic behavior).
- Indexed snippets for common APIs (movement, inventory, entities, events).
- Optional "doc cards" in prompt context for high-frequency use.

REPL API:

- `docs.find("pathfinder")`
- `docs.read("mineflayer.bot.chat")`
- `docs.example("collectBlock")`

## 4) Self-Evolution Workflow (Proposal First)

Add a governance pipeline before any self-modification:

1. Agent inspects code/docs/runtime.
2. Agent emits a **Change Proposal** object:
   - rationale
   - files impacted
   - risks
   - test plan
   - rollback plan
3. Human reviews proposal.
4. Optional apply step (future): patch generation + tests + review gate.

Proposed REPL APIs:

- `evolve.propose(spec)`
- `evolve.listProposals()`
- `evolve.getProposal(id)`
- `evolve.reject(id, reason)` / `evolve.approve(id)` (human-mediated)

## 5) Event Hooks

Support persistent declarative hooks that trigger scripts on conditions.

Hook model:

- Trigger: chat/perception/feedback/time tick/custom.
- Condition: JS predicate over `ctx`/`last`/`mem`.
- Action: script body or tool calls.
- Policy: debounce, cooldown, max executions, priority.

API sketch:

- `hooks.register({ name, on, when, script, policy })`
- `hooks.list()`
- `hooks.disable(name)` / `hooks.enable(name)` / `hooks.remove(name)`

Guardrails:

- Prevent recursive storms (hook triggers caused by own outputs).
- Global execution budget per minute.
- Trace each hook invocation.

## 6) Background Daemons

Allow optional long-running tasks for monitoring/planning loops.

Potential uses:

- Patrol/scan loops.
- Inventory housekeeping.
- Threat watcher with alerts.
- Social etiquette responder.

API sketch:

- `daemon.start({ name, script, intervalMs, policy })`
- `daemon.stop(name)`
- `daemon.status(name)` / `daemon.list()`

Constraints:

- Strict per-daemon CPU/time budgets.
- Kill switch and watchdog timeout.
- No direct world mutation unless via validated tool intents.

---

## Architecture Sketch

## REPL Context Modules

- `ctx` (readonly, per-turn injected)
- `last` (readonly, last outcome)
- `mem` (persistent writable)
- `introspect` (readonly API)
- `repo` (read-only at first)
- `docs` (read-only retrieval)
- `hooks` (managed registration)
- `daemon` (managed lifecycle)
- `evolve` (proposal orchestration)

## Runtime Services (outside REPL sandbox)

- Introspection service
- Repo/document index service
- Hook scheduler
- Daemon supervisor
- Proposal registry + audit log

---

## Rollout Plan

## Phase 0 - Foundation Hardening

- Finalize `ctx/last/mem` conventions and docs.
- Add telemetry on script size, execution time, action count.
- Add rate limits and anti-loop protections.

## Phase 1 - Read-Only Introspection + Repo/Docs Read

- Implement `introspect.*`, `repo.list/read/search`, `docs.find/read`.
- Add allowlist + secret/path guards.
- Add prompt conventions for using these APIs responsibly.

## Phase 2 - Proposal-Only Self-Evolution

- Implement `evolve.propose` and proposal registry.
- Define proposal schema + scoring rubric.
- Add review UI/log stream hooks.

## Phase 3 - Hooks + Daemons (Constrained)

- Implement managed hooks with cooldown/budgets.
- Implement supervised daemon runner.
- Add kill switch + watchdog + per-feature flags.

## Phase 4 - Assisted Apply (Optional)

- Agent can prepare patch candidates + test commands.
- Human approval required before applying.
- Automatic rollback metadata and validation report.

---

## Prompt/Policy Conventions to Add

- Prefer world tools for immediate actions.
- Use `repo/docs/introspect` for understanding before proposing changes.
- Never assume write privileges; use `evolve.propose`.
- Keep hook/daemon logic idempotent and bounded.
- Explain intent in `mem` notes before major behavior changes.

---

## Risk Register

- **Runaway autonomy**: hooks/daemons creating infinite loops.
- **Context bloat**: huge introspection outputs inflating token use.
- **Unsafe self-editing**: bad proposals that degrade behavior.
- **Secret leakage**: repo read accidentally exposing credentials.
- **Operational complexity**: too many async subsystems reducing predictability.

Mitigations:

- Hard limits + quotas + cooldowns.
- Strong allowlists and redaction layers.
- Proposal-only first, human gates later.
- Feature flags for every new subsystem.
- Rich tracing and one-command emergency disable.

---

## Open Questions (For Discussion)

1. Should proposal approval live in chat only, or also in a local UI/CLI queue?
2. How much repo scope should be readable by default?
3. Should hooks/daemons be persisted across restarts?
4. Do we want separate "safe mode" and "experimental mode" presets?
5. What exact success metrics define "self-evolution is helping"?

---

## Suggested First Milestone

Implement only:

- `introspect.runtime/tools/health`
- `repo.list/read/search` (read-only, strict limits)
- `docs.find/read` (curated Mineflayer docs)
- `evolve.propose` registry (no apply)

This gives strong value quickly while keeping risk low.