loopy-loop 0.2.0__tar.gz → 0.3.0__tar.gz

loopy_loop-0.3.0/.github/workflows/docs-deploy.yml

@@ -0,0 +1,66 @@
+name: Docs Site
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "website/**"
+      - ".github/workflows/docs-deploy.yml"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "website/**"
+      - ".github/workflows/docs-deploy.yml"
+  workflow_dispatch:
+
+# Allow GITHUB_TOKEN to deploy to GitHub Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      # `next build` type-checks the project and generates .next/types, so a
+      # separate pre-build `tsc` step is intentionally omitted (it would run
+      # before those generated types exist).
+      - name: Build static site (Next.js export + Pagefind index)
+        run: npm run build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/out
+
+  deploy:
+    # Only publish from main; PRs run the build job above as a check.
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    # Serialize production deployments only, so PR build-checks stay concurrent.
+    concurrency:
+      group: "pages-deploy"
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

loopy_loop-0.3.0/AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md — working agreement for this repo
+
+`loopy-loop` runs long-running AI agent workflows inside a repository. A FastAPI
+**coordinator** owns durable loop state in files and picks the next workflow; a single
+**worker** runs each assignment through `team-harness`. Continuity lives in files and git,
+not in a chat transcript. Read `README.md` for the user-facing model, and
+`design/decisions.md` for *why the system is the way it is*.
+
+This file is the working agreement for any agent (or human) changing this repo. Three
+things are non-negotiable.
+
+## Rule 1 — Respect the deliberate decisions; don't "fix" them
+
+`design/decisions.md` is the canonical Architecture Decision Log (D1, D2, …). **Several
+decisions there look like defects if you only skim the code, and are recorded precisely so
+they don't get "fixed" by accident.** Before changing behavior in these areas, read the
+relevant decision (and its companion design doc):
+
+- **D3 — iteration success ≠ "work is good."** `IterationResult.success` means only that
+  the harness ran without erroring. Do not make it consult worker exit codes / infer
+  semantic success. The eval layer (`control.json` + `goal_check.json`) decides quality.
+- **D4 — evaluation is LLM-as-judge; agents don't author deterministic checks.** Do not
+  "add deterministic checks" to the stock `inner_outer_eval` eval workflows. (A target
+  repo that owns its own test suite is a different case — see D4.)
+- **D2 — single worker is deliberate.** Do not add parallel loopy workers as a scaling
+  feature.
+- **D5 — full autonomy with a last-resort escape hatch.** See Rule 2.
+
+If you believe a decision is genuinely wrong, propose amending `design/decisions.md`
+(state what changes and why) — do not silently contradict it in code.
+
+## Rule 2 — Autonomy is the goal; the human escape hatch is a LAST resort (D5)
+
+This system is meant to run **fully autonomously, with no human in the loop**. Human
+involvement is a last resort, never a normal step.
+
+- **The one sanctioned escape hatch already exists.** When a workflow hits a *genuinely
+  terminal* blocker — a decision only a human can make, a missing credential, a
+  billable/destructive action it isn't permitted to take — it writes the session
+  `control.json` with:
+  ```json
+  {"state": "stopped", "reason": "<specific terminal blocker>", "stop_reason": "unresolvable_error", "schema_version": 1}
+  ```
+  This stops the loop as terminal, with a recorded reason. That is the entire
+  human-in-the-loop mechanism, and it is enough.
+- **Exhaust autonomous options first.** Re-scope, retry with a better child goal, route
+  around the blocker. Reach for `unresolvable_error` only when a blocker is genuinely
+  unavoidable without a human. It should fire rarely.
+- **Make the give-up legible.** The recorded blocker is the only thing a human sees when a
+  run stops — state exactly what was missing and what was tried.
+- **Do NOT build or assume a preferred human gate.** No `paused` / `waiting_for_human`
+  state, no `gate_request.json`, no external-action approval flow. That was considered and
+  rejected (D5; `design/designs/improvement-proposals.md` P0.2). Do not pause a run to ask
+  a question when you could either solve it autonomously or stop cleanly with
+  `unresolvable_error`.
+
+## Rule 3 — Design and decision docs must be understandable cold, by future agents AND humans
+
+A design or decision doc is read by someone who was **not** in the conversation that
+produced it — a future agent with no memory of this session, or a human who is not a
+specialist. Write for them.
+
+- **Explain, don't just name.** Naming a mechanism ("the ping-pong protocol", "cadence
+  scheduling", "the double loop") is not explaining it. State, in plain language, *what it
+  is, what problem it solves, and why we chose it*, with a concrete example where it helps.
+- **The reasoning lives in the doc, not in your head.** Don't rely on a future reader
+  re-deriving the rationale. A decision-log entry may state the conclusion tersely; the
+  companion design section must be self-contained.
+- **Anchor claims in the code.** Reference the file/function (e.g. `coordinator_app.py`,
+  `harness_runner.py`) so a reader can verify — but lead with the plain-English meaning.
+- **Keep `design/` honest about status.** `design/designs/` is binding; `design/analysis/`
+  is working notes (may be superseded); `improvement-proposals.md` is *proposed, not
+  decided*. Don't cite a proposal as if it were a decision.
+
+When in doubt on any rule, favor the version a stranger could read cold and fully
+understand.
+
+---
+
+Note: `CLAUDE.md` points here. Keep this file as the single source; don't fork the two.

loopy_loop-0.3.0/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+## 0.3.0 (breaking)
+
+**Breaking API change — `/register` requires the worker's process identity.**
+A register without a `worker` object is rejected with HTTP 400. Pre-0.3
+workers cannot register against a 0.3 coordinator; upgrade workers and
+coordinator together (they normally ship in the same install).
+
+- **Worker liveness verification (D7).** The worker sends its process
+  identity (hostname + pid + a pid-reuse-proof start-time token) with
+  `/register` and `/finished`; the coordinator stamps it onto the dispatched
+  task. A `/register` while the recorded worker is *verifiably still alive*
+  returns HTTP 409 instead of abandoning live work — closing the
+  duplicate-work window. Unverifiable identities (remote hosts, or a
+  team-harness without process identity) keep the pre-existing
+  assume-abandoned recovery behavior. Because every dispatched task now has
+  a recorded owner, a stale `/finished` is replayed **only to that owner**
+  (anyone else gets HTTP 409) — a task persisted by a pre-identity version
+  keeps the legacy replay for that one resume.
+- **Orphaned-agent recovery (P2.5 / TH-D5 consumer side).** When a worker is
+  confirmed dead with nothing recoverable, the coordinator applies
+  `recovery_policy` (new coordinator-side config, NOT part of the wire
+  snapshot; default `drain`, one shared `recovery_drain_timeout_s` deadline,
+  default 600s) to agent processes the dead worker's harness run left behind,
+  via team-harness's process reaper: drained agents finish and their repo
+  edits survive; a `salvage.json` in the interrupted iteration directory
+  records what was handled; the history entry is `abandoned_after_<policy>`
+  when anything settled. Recovery runs OUTSIDE the state lock (`loopy
+  status`/`stop` stay usable while draining), validates that each discovered
+  run record actually belongs to the iteration, is same-host-only (a worker
+  identity from another hostname skips reaping), and refuses to dispatch
+  replacement work (HTTP 409) when any orphan may still be running or when
+  team-harness's parent-liveness guard reports the run's owner alive.
+  Requires team-harness with the process reaper (> 0.2.10); older versions
+  skip orphan recovery gracefully.
+- A stale `/finished` from a **different identified worker** now gets HTTP 409
+  instead of a second copy of the live task; unknown identities keep the
+  pre-existing stale-retry behavior. State-lock contention surfaces as a clean
+  HTTP 503 (and friendly CLI errors) instead of raw tracebacks.
+- The bundled worker uses an unbounded read timeout on `/register` only
+  (recovery can legitimately block registration up to the drain deadline),
+  keeps the bounded timeout on `/finished`, and exits with code 3 on a 409.
+
+## 0.2.1
+
+- Improve README onboarding, install, initialization, configuration, and logging docs.
+- Update package and skill descriptions to avoid unclear repository-scope jargon.
+
+## 0.2.0 (breaking)
+
+**Breaking API change — drop leases, polling, and worker identity.**
+
+The three-endpoint API (`POST /workers/register`, `POST /workers/{worker_id}/next`,
+`POST /workers/{worker_id}/finished`) is replaced by a two-endpoint ping-pong API:
+
+- `POST /register` — returns `TaskResponse` directly (`action: "run"` or `"stop"`).
+- `POST /finished` — returns `TaskResponse` for the next task or stop signal.
+
+The `"wait"` action is gone. The worker loop is now a simple `while task.action == "run"`
+loop with no polling.
+
+**Removed models and fields:**
+- `WorkerState`, `ActiveAssignment`, `RegisterWorkerResponse`, `NextActionResponse` removed.
+- `assignment_id` removed from `FinishedRequest` and `HistoryEntry`.
+- `worker_id` removed from `HistoryEntry`.
+- `workers` dict and `active_assignment` removed from `LoopState`.
+- Constants `DEFAULT_LEASE_SECONDS`, `DEFAULT_POLL_INTERVAL_SECONDS`,
+  `DEFAULT_FINISHED_RETRY_ATTEMPTS`, `DEFAULT_FINISHED_RETRY_BACKOFF_SECONDS`,
+  `WAIT_ACTION` removed.
+
+**Added:**
+- `CurrentTask` model replaces `ActiveAssignment` (no `worker_id`, no lease).
+- `TaskResponse` model returned by both `/register` and `/finished`.
+- `LoopState.current_task: CurrentTask | None` replaces `active_assignment`.
+
+**Crash recovery:** If a worker crashes mid-run, the next `/register` call detects the
+orphaned `current_task`, records it in history as `error="abandoned"`, and dispatches
+fresh work.
+
+**Migration note:** Existing `state.json` files containing `active_assignment` or `workers`
+fields will have those fields silently dropped on first read (Pydantic ignores unknown
+fields). Any in-flight run at upgrade time will lose its `active_assignment` record without
+a history entry. Drain all workers before deploying this version.
+
+## 0.1.0
+
+- Initial release.

loopy_loop-0.3.0/CLAUDE.md

@@ -0,0 +1,17 @@
+# CLAUDE.md
+
+The working agreement for this repo lives in **[`AGENTS.md`](./AGENTS.md)** — read it first.
+It is the single source; this file only points to it so the two never diverge.
+
+Quick orientation for what most often trips up a change here:
+
+- **`design/decisions.md`** is the canonical decision log. Several decisions look like
+  defects if you only skim the code and are recorded so they don't get "fixed" by accident
+  (notably **D3** iteration-success semantics and **D4** LLM-as-judge evaluation).
+- **Autonomy is the goal; the human escape hatch is a last resort (D5).** The system runs
+  unattended. When a workflow hits a genuinely terminal blocker it stops by writing
+  `control.json` with `stop_reason: "unresolvable_error"` and a specific recorded reason —
+  that is the entire human-in-the-loop mechanism. Do **not** build or assume a preferred
+  `paused` / `waiting_for_human` gate; exhaust autonomous options first, then stop cleanly.
+
+See `AGENTS.md` Rules 1–3 for the full agreement.

{loopy_loop-0.2.0 → loopy_loop-0.3.0}/Makefile

@@ -7,12 +7,12 @@
 ## Start Claude Code with MCP configuration
 claude:
 	@test -f .mcp.json || (echo "Error: .mcp.json not found. Please create it first." && exit 1)
-	PATH="$(HOME)/.bun/bin:$(PATH)" CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 TELEGRAM_STATE_DIR=$(PWD)/.claude/channels/telegram claude --dangerously-skip-permissions --mcp-config .mcp.json --remote-control
+	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 CLAUDE_CODE_ENABLE_AUTO_MODE=1 claude --dangerously-skip-permissions --mcp-config .mcp.json --remote-control
 
 ## Continue previous Claude Code session
 claudecontinue:
 	@test -f .mcp.json || (echo "Error: .mcp.json not found. Please create it first." && exit 1)
-	PATH="$(HOME)/.bun/bin:$(PATH)" CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 TELEGRAM_STATE_DIR=$(PWD)/.claude/channels/telegram claude --dangerously-skip-permissions --mcp-config .mcp.json --continue --remote-control
+	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 CLAUDE_CODE_ENABLE_AUTO_MODE=1 claude --dangerously-skip-permissions --mcp-config .mcp.json --continue --remote-control
 
 ## Codex
 codex: