166 lines
8.8 KiB
Markdown
166 lines
8.8 KiB
Markdown
# EpiphanyAgent
|
|
|
|
A cheap prototype for testing whether typed external state makes a strong model less likely to build an impressive pile of locally plausible nonsense.
|
|
|
|
## Premise
|
|
|
|
Most coding agents are one token stream pretending to be a planner, scratchpad, architect, and release engineer at the same time. This workspace separates those roles outside the model first.
|
|
|
|
The goal is not to prove a new frontier architecture in a weekend. The goal is to find out whether explicit state channels and bounded controller actions reduce drift enough to matter.
|
|
|
|
## Core Artifacts
|
|
|
|
- `AGENTS.md`: project-specific instructions for future Codex sessions
|
|
- `state/map.yaml`: canonical, slow-changing model of the task or system
|
|
- `state/scratch.md`: temporary reasoning for one subgoal
|
|
- `state/branches.json`: branch hypotheses and branch outcomes
|
|
- `state/evidence.jsonl`: verifier outputs, acceptance reasons, and reversions
|
|
- `protocol/controller-actions.md`: allowed actions and write rules
|
|
- `notes/fresh-workspace-handoff.md`: concise summary for a fresh workspace
|
|
- `notes/epiphany-fork-implementation-plan.md`: current implementation plan for the Epiphany fork architecture
|
|
- `notes/codex-repository-algorithmic-map.md`: current machine map of vendored Codex
|
|
- `notes/epiphany-current-algorithmic-map.md`: current machine map of the Epiphany fork itself
|
|
- `notes/epiphany-core-harness-surfaces.md`: where Epiphany should patch into that machine
|
|
- `notes/architecture-rationale.md`: why the map/scratch/evidence architecture exists
|
|
- `tools/epiphany_state.py`: tiny CLI for inspecting and updating branch/evidence state
|
|
- `eval-plan.md`: how to compare this protocol against plain prompting
|
|
|
|
## Current Direction
|
|
|
|
This repo is no longer pretending the solution is "just prompt harder."
|
|
|
|
The working design now is:
|
|
|
|
- fork Codex into Epiphany, an opinionated harness that makes models keep an explicit model of the thing they are changing
|
|
- treat typed thread state as the primary artifact and the UI as a reflection/steering layer
|
|
- keep the machine map as two linked graphs: architecture and dataflow
|
|
- preserve rich natural-language explanations alongside code refs, because language is still the model's least embarrassing organ
|
|
- use specialist agents with shared typed state and private scratch, not one heroic context trying to cosplay a whole team
|
|
- add repo-local hybrid retrieval instead of making every role rediscover the repo with `rg` and raw stubbornness
|
|
- use an explicit typed state-update surface for durable observations, evidence, map/frontier edits, and churn state instead of letting retrieval or transcript drift mutate the map sideways
|
|
- treat compaction as a role-specific state transition with safe points and explicit checkpoints, not hidden brain damage
|
|
- bake an explicit pre-compaction persistence workflow into the process, because forgetting to write down what matters and then acting surprised is not a serious engineering method
|
|
- make Epiphany an opinionated software development agent, not a generic assistant with some extra tags bolted on
|
|
|
|
## Current Repository State
|
|
|
|
- `vendor/codex` is the real target and is tracked directly in the parent repo
|
|
- `epiphany-core/` is the repo-owned crate that now holds the thicker Epiphany prompt, rollout replay, and retrieval/indexing organs
|
|
- third-party OpenCodex forks were audited and removed
|
|
- the Codex machine map and Epiphany harness spec have both been written and iterated enough to stop hand-waving
|
|
- Phase 1 durable Epiphany state, Phase 2 prompt integration, a minimal Phase 3 typed client read surface, the Phase 4 hybrid retrieval/indexing slice, the first typed Epiphany state-update surface, the first typed distillation/proposal surface, and the first explicit promotion gate are all landed and verified
|
|
- the next concrete step is richer map/churn promotion on top of the explicit distill/promote/update surfaces, not more retrieval plumbing and not GUI paint
|
|
|
|
## Current Slice Status
|
|
|
|
Phase 1 landed:
|
|
|
|
- add minimal Epiphany protocol types
|
|
- store Epiphany state in Codex `SessionState`
|
|
- persist one Epiphany rollout snapshot per real user turn
|
|
- restore it through rollout reconstruction
|
|
- patch exhaustive `RolloutItem` matches
|
|
- add persistence/replay compatibility tests
|
|
|
|
Phase 2 landed:
|
|
|
|
- add a dedicated `EpiphanyStateInstructions` developer fragment
|
|
- render a bounded `<epiphany_state>` summary from `SessionState.epiphany_state`
|
|
- inject it during `Session::build_initial_context`
|
|
- verify inclusion, omission, resume, and snapshot behavior
|
|
|
|
Phase 3 landed:
|
|
|
|
- add optional typed `epiphanyState` to hydrated app-server `Thread` payloads
|
|
- hydrate it from live loaded-thread state when available
|
|
- fall back to rollout reconstruction with rollback/compaction semantics for stored thread reads
|
|
- keep dedicated Epiphany update RPCs and live notifications deferred for now
|
|
|
|
Phase 4 landed:
|
|
|
|
- add a repo-local hybrid retrieval subsystem
|
|
- expose typed retrieval state and typed `thread/epiphany/retrieve`
|
|
- keep retrieval read-only
|
|
- add explicit `thread/epiphany/index` for Qdrant-backed persistent semantic indexing
|
|
- preserve exact/path lookup and BM25 fallback when the persistent semantic backend is stale, missing, or unavailable
|
|
- move the heavy Epiphany-owned implementation into `epiphany-core/`, leaving vendored Codex with thin adapters plus the typed protocol/thread/app-server seam
|
|
|
|
State-update slice landed:
|
|
|
|
- add experimental loaded-thread-only `thread/epiphany/update`
|
|
- append observations and evidence through typed state patches
|
|
- replace bounded typed fields such as objective, subgoals, graph frontier/checkpoint, scratch, churn, and mode
|
|
- bump Epiphany state revision and persist an immediate rollout snapshot
|
|
- keep retrieval read-only and indexing explicit instead of mixing query and mutation paths
|
|
|
|
Distillation slice landed:
|
|
|
|
- add experimental loaded-thread-only `thread/epiphany/distill`
|
|
- turn one explicit source/status/text observation into deterministic observation/evidence records
|
|
- return a patch plus `expectedRevision` for explicit promotion through `thread/epiphany/update`
|
|
- keep distillation read-only so proposals do not become durable facts without a promotion step
|
|
|
|
Promotion slice landed:
|
|
|
|
- add experimental loaded-thread-only `thread/epiphany/promote`
|
|
- require verifier evidence before promotion
|
|
- reject failed promotion candidates with structured reasons and no state mutation
|
|
- accepted candidates flow through the existing durable update path
|
|
|
|
## Basic Loop
|
|
|
|
1. Observe the task, repo state, and current verifier outputs.
|
|
2. Update `state/map.yaml` only when understanding stabilizes.
|
|
3. Use `state/scratch.md` for one bounded subgoal at a time.
|
|
4. Propose one change or one answer.
|
|
5. Verify against task success, map consistency, and simplicity.
|
|
6. Record evidence.
|
|
7. Commit, compare branches, or backtrack.
|
|
|
|
## Pre-Compaction Discipline
|
|
|
|
This part is not optional if the work is nontrivial.
|
|
|
|
Before compaction, handoff, or a deliberate phase boundary:
|
|
|
|
1. sync `state/map.yaml`
|
|
2. append `state/evidence.jsonl`
|
|
3. refresh `notes/fresh-workspace-handoff.md`
|
|
4. state the next action plainly
|
|
|
|
If context pressure is clearly rising, do this **before** the hard compaction hits. A harness that only remembers to save itself after the blackout is still acting like a chat transcript with a superiority complex.
|
|
|
|
Epiphany should eventually make this automatic. Until then, we do it on purpose.
|
|
|
|
## Why This Exists
|
|
|
|
Pinned notes inside one giant prompt are better than nothing, but they are still one token soup. This workspace treats map, scratch, and output as different artifacts with different write rules.
|
|
|
|
That may still turn out to be elaborate prompt theater. Fine. At least it will be falsifiable prompt theater.
|
|
|
|
## Tiny CLI
|
|
|
|
Examples:
|
|
|
|
```powershell
|
|
python .\tools\epiphany_state.py status
|
|
python .\tools\epiphany_state.py add-evidence --type verify --status ok --note "Map and patch still agree"
|
|
python .\tools\epiphany_state.py add-branch --id b1 --hypothesis "Smaller verifier beats elaborate verifier"
|
|
python .\tools\epiphany_state.py close-branch --id b1 --status rejected --note "More ceremony, no better signal"
|
|
```
|
|
|
|
## Licensing
|
|
|
|
The root `LICENSE` file is now an operative repository license notice, not just
|
|
a throat-clearing draft. In short: `vendor/codex/**` and other third-party
|
|
material keep their upstream licenses, while Project-Authored Material outside
|
|
`vendor/codex/**` is publicly available under PolyForm Noncommercial 1.0.0 and
|
|
is also intended to be available under separate commercial terms by written
|
|
agreement. That makes the repo source-available and dual-licensed, not OSI open
|
|
source as a whole.
|
|
|
|
External contributions require the EpiphanyAgent Contributor License Agreement
|
|
in `CONTRIBUTOR_LICENSE_AGREEMENT.md`, or a separate written agreement accepted
|
|
by the Project Steward. The point is simple: contributors keep ownership, but
|
|
the project gets the right to sublicense and relicense contributions without
|
|
future archaeology through old pull requests.
|