cyph3rasi
109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
# Hop agent protocol
|
|
|
|
## State graph
|
|
|
|
```text
|
|
A accepted
|
|
├─ P prompt, persisted before effects
|
|
│ └─ C checkpoint
|
|
│ └─ R proposal
|
|
└─ P independent prompt
|
|
|
|
A + R ──land──> A next accepted state
|
|
```
|
|
|
|
State prefixes:
|
|
|
|
| Prefix | Kind | Meaning |
|
|
|---|---|---|
|
|
| `A_` | accepted | Canonical project revision |
|
|
| `P_` | prompt | Exact instruction and pre-effect context |
|
|
| `C_` | checkpoint | Immutable workspace progress |
|
|
| `R_` | proposal | Frozen candidate result |
|
|
| `F_` | failed | Durable failed execution or validation state |
|
|
| `X_` | cancelled | Durable cancelled state |
|
|
|
|
Prompt, checkpoint, and proposal states may reference identical Git trees while remaining distinct causal occurrences.
|
|
|
|
## Environment contract
|
|
|
|
| Variable | Purpose |
|
|
|---|---|
|
|
| `HOP_ROOT` | Canonical project root containing `.hop/hop.db` |
|
|
| `HOP_STATE_ID` | Prompt state authorizing the current instruction |
|
|
| `HOP_TASK_ID` | Logical task grouping related prompts and attempts |
|
|
| `HOP_ATTEMPT_ID` | Current agent approach/run |
|
|
| `HOP_WORKSPACE` | Only directory the agent may modify |
|
|
|
|
Treat missing variables as an invalid agent launch. Do not infer an attempt from a nearby worktree when causality matters.
|
|
|
|
## Command contract
|
|
|
|
### Human or controller
|
|
|
|
```bash
|
|
hop init
|
|
hop start --agent <name> "<exact initial prompt>"
|
|
hop env <prompt-state>
|
|
hop prompt --from <state> "<exact follow-up prompt>"
|
|
hop land <proposal> -- <final validation command>
|
|
hop undo
|
|
```
|
|
|
|
`hop start` creates the task, attempt, prompt state, and detached workspace before returning. The controller may deliver the prompt only after exit `0`.
|
|
|
|
`hop prompt` captures a checkpoint of current workspace effects before creating the follow-up prompt state.
|
|
|
|
### Agent
|
|
|
|
```bash
|
|
hop state "$HOP_STATE_ID" --json
|
|
hop status --json
|
|
hop check "$HOP_STATE_ID" -- <command>
|
|
hop propose --summary "<summary>" "$HOP_STATE_ID"
|
|
```
|
|
|
|
`hop check` snapshots the attempt and runs the command in a detached worktree materialized from that exact checkpoint. Edits made concurrently in the live workspace do not change the tested tree.
|
|
|
|
`hop propose` freezes the current nonignored workspace tree. Later workspace edits cannot change the proposal.
|
|
|
|
`hop land` compares paths changed by the proposal with paths accepted since its base. Any shared changed path blocks landing. Disjoint proposals are composed with Git three-tree plumbing and may then be validated on the final tree.
|
|
|
|
## Exit codes
|
|
|
|
| Code | Meaning |
|
|
|---:|---|
|
|
| `0` | Success |
|
|
| `1` | Git, SQLite, filesystem, or internal error |
|
|
| `2` | Invalid CLI usage |
|
|
| `20` | Overlap or conservative conflict block |
|
|
| `21` | Accepted or attempt head changed during compare-and-swap |
|
|
| `22` | Validation command failed |
|
|
|
|
A failed `hop check` or final landing check persists its evidence. A blocked or failed landing does not advance accepted state.
|
|
|
|
## Human launch sequence
|
|
|
|
```bash
|
|
hop init
|
|
hop start --agent codex "Add password reset emails"
|
|
```
|
|
|
|
Use the returned workspace and environment to launch the agent. For example, conceptually:
|
|
|
|
```bash
|
|
eval "$(hop env P_...)"
|
|
<agent-command> "<the same exact prompt>"
|
|
```
|
|
|
|
The exact agent command is harness-specific. Until a Hop process adapter intercepts prompts automatically, follow-up prompts must also pass through `hop prompt` before the agent acts.
|
|
|
|
## Failure handling
|
|
|
|
- **Missing Hop environment:** stop before editing and request a Hop-controlled launch.
|
|
- **Check failure:** fix the live workspace, checkpoint/check again, then create a new proposal.
|
|
- **Frozen proposal needs changes:** record a follow-up prompt; never mutate the stored proposal.
|
|
- **Overlap on landing:** retain both lineages and reconcile through a new prompt against current accepted state.
|
|
- **Ref inconsistency:** run `hop doctor`; use `hop doctor --repair` only outside final validation.
|
|
- **Secrets:** prompt text and check output are stored locally without encryption in the alpha. Never place credentials in them.
|