Merge origin/main into v0.8.58-3026-hooks-v2 — keep both the #3026 hook fold helpers and the #3027 command_denies_tool gate in turn_loop
This commit is contained in:
Claude
@@ -0,0 +1,135 @@
|
||||
# Agent Runner Protocol
|
||||
|
||||
How a headless agent (DeepSeek V4 on a DigitalOcean droplet, or any codewhale exec caller) picks up, implements, verifies, and delivers a milestone issue — fully autonomously.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `gh` CLI authenticated with a fine-grained PAT scoped to `Hmbown/CodeWhale` (Contents RW, Issues RW, PRs RW, Metadata R)
|
||||
- `codewhale` binary on `$PATH` (v0.8.57+)
|
||||
- `DEEPSEEK_API_KEY` (or equivalent provider key) exported in the agent user's shell
|
||||
- A `git worktree` per issue (never commit directly to `main`)
|
||||
|
||||
---
|
||||
|
||||
## The loop
|
||||
|
||||
### 1. Pick
|
||||
|
||||
```bash
|
||||
gh issue list \
|
||||
--repo Hmbown/CodeWhale \
|
||||
--milestone v0.8.58 \
|
||||
--label agent-ready \
|
||||
--state open \
|
||||
--json number,title,url
|
||||
```
|
||||
|
||||
Choose an issue. Prefer `release-blocker` → `bug` → `enhancement` order.
|
||||
Do not pick an issue already labeled `agent-in-progress`.
|
||||
|
||||
### 2. Claim
|
||||
|
||||
```bash
|
||||
gh issue edit <N> --add-label agent-in-progress --remove-label agent-ready
|
||||
```
|
||||
|
||||
This prevents other agents from picking the same issue.
|
||||
|
||||
### 3. Isolate
|
||||
|
||||
```bash
|
||||
cd /opt/whalebro/codewhale
|
||||
git fetch origin
|
||||
git worktree add ../worktrees/issue-<N> -b agent/<N>-<slug> origin/main
|
||||
cd ../worktrees/issue-<N>
|
||||
```
|
||||
|
||||
Every issue gets its own branch and worktree. The branch name convention is `agent/<issue-number>-<short-slug>`.
|
||||
|
||||
### 4. Execute
|
||||
|
||||
```bash
|
||||
gh issue view <N> --json body -q .body | \
|
||||
codewhale exec --auto --output-format stream-json "$(cat)"
|
||||
```
|
||||
|
||||
The agent reads the issue body and implements the fix. Use a tmux session per issue so the run survives SSH disconnects:
|
||||
|
||||
```bash
|
||||
tmux new-session -d -s "issue-<N>" \
|
||||
"gh issue view <N> --json body -q .body | \
|
||||
codewhale exec --auto --output-format stream-json \"\$(cat)\" 2>&1 | tee /tmp/issue-<N>.log"
|
||||
```
|
||||
|
||||
For resuming an interrupted run (`--continue` picks up the most recent
|
||||
session for this workspace; `--resume latest` only exists in the interactive
|
||||
TUI):
|
||||
|
||||
```bash
|
||||
codewhale exec --auto --output-format stream-json --continue "..."
|
||||
```
|
||||
|
||||
### 5. Verify
|
||||
|
||||
Run the exact commands from the issue's **Verification** section. If they pass, proceed. If they fail, loop back to step 4 with the error output as context, or label `needs-human`.
|
||||
|
||||
### 6. Deliver
|
||||
|
||||
```bash
|
||||
gh pr create \
|
||||
--repo Hmbown/CodeWhale \
|
||||
--base main \
|
||||
--title "<descriptive title>" \
|
||||
--body "Closes #<N>" \
|
||||
--label v0.8.58
|
||||
```
|
||||
|
||||
All delivery is via PR — never push to `main` directly. Human review is required before merge.
|
||||
|
||||
### 7. On blockage
|
||||
|
||||
```bash
|
||||
gh issue edit <N> --add-label needs-human --remove-label agent-in-progress
|
||||
gh issue comment <N> --body "Blocked: <reason>. Human decision needed."
|
||||
```
|
||||
|
||||
Common blockers: missing credentials, ambiguous scope, test environment unavailable, network outage.
|
||||
|
||||
---
|
||||
|
||||
## Label semantics
|
||||
|
||||
| Label | Meaning | Auto-applied? |
|
||||
|---|---|---|
|
||||
| `agent-ready` | Body has all six template sections; a remote agent may claim it | Yes (template) |
|
||||
| `agent-in-progress` | Claimed by an agent run; do not double-pick | Manual (step 2) |
|
||||
| `needs-human` | Agent blocked; requires human decision or credentials | Manual (step 7) |
|
||||
| `autonomous-ready` | Legacy nightly-loop label; distinct from `agent-ready` | No |
|
||||
|
||||
The `autonomous-ready` label is for the legacy nightly loop (external automation).
|
||||
New work uses `agent-ready`.
|
||||
|
||||
---
|
||||
|
||||
## Safety rules
|
||||
|
||||
1. **PR-only delivery.** Never commit to `main`. Every change is a branch + PR.
|
||||
2. **No force-push.** `git push --force` is forbidden.
|
||||
3. **Secrets never in argv, history, or logs.** API keys, PATs, and credentials live in `/etc/codewhale/*.env` and are sourced into the agent user's shell. The runtime API listens on `127.0.0.1:7878` only. Telegram bridge chats are allowlisted.
|
||||
4. **Human reviews every PR.** The droplet loop delivers PRs; a human on the laptop reviews and merges.
|
||||
5. **One issue per worktree.** No cross-contamination between concurrent agent runs.
|
||||
|
||||
---
|
||||
|
||||
## Issue body format
|
||||
|
||||
Every `agent-ready` issue must have these six sections (enforced by `.github/ISSUE_TEMPLATE/agent-task.yml`):
|
||||
|
||||
1. **Goal / Why** — what problem, why now
|
||||
2. **Scope / Plan** — numbered steps with file paths
|
||||
3. **Key files** — paths to read first
|
||||
4. **Acceptance criteria** — behavior-level checkboxes
|
||||
5. **Verification** — exact shell commands
|
||||
6. **Out of scope** — explicit non-goals
|
||||
|
||||
The body must be self-sufficient: a fresh clone agent with no conversation context must be able to execute it.
|
||||
@@ -11,6 +11,7 @@ Bindings are not (yet) user-configurable — tracked for a future release (#436,
|
||||
| `F1` or `Ctrl-/` | Toggle the help overlay |
|
||||
| `Ctrl-K` | Open the command palette (slash-command finder) |
|
||||
| `Ctrl-C` | Cancel current turn / dismiss modal / arm-then-confirm quit |
|
||||
| `Ctrl-B` | Background the running foreground shell command (turn continues; the command becomes a `/jobs` background job) |
|
||||
| `Ctrl-D` | Quit (only when the composer is empty) |
|
||||
| `Tab` | Cycle TUI mode: Plan → Agent → YOLO → Plan |
|
||||
| `Shift-Tab` | Cycle reasoning effort: off → high → max → off |
|
||||
|
||||
@@ -28,7 +28,7 @@ Checks:
|
||||
3. Confirm no local sandbox/permission deadlock in tool output
|
||||
|
||||
Actions:
|
||||
1. If a foreground shell command is running, press `Ctrl+B` and choose whether to background it or cancel the current turn.
|
||||
1. If a foreground shell command is running, press `Ctrl+B` to move it to the background (the turn keeps running and the command becomes a background job under `/jobs`); use `Ctrl+C` instead if you want to cancel the turn.
|
||||
2. If the command was started in the background, ask the assistant to cancel it with `exec_shell_cancel` and the returned task id.
|
||||
3. Use `Esc` or `Ctrl+C` to interrupt the current turn when you want to stop the request itself.
|
||||
4. Retry prompt; if still failing, restart TUI.
|
||||
|
||||
Reference in New Issue
Block a user