chore: import upstream snapshot with attribution

2026-07-13 13:10:45 +08:00
commit 4b6817381b
3933 changed files with 525247 additions and 0 deletions
@@ -0,0 +1,79 @@
+---
+title: "Pi coding tasks"
+description: "Let OpenSRE hand a coding task to the Pi agent, which edits the working tree and returns a diff."
+---
+
+The **Pi coding tool** lets OpenSRE submit a coding task to the [Pi](https://pi.dev) agent.
+Pi edits files in a workspace to implement the change and returns a summary plus the git diff.
+It **does not commit, push, or open a pull request** — it only edits the working tree so you can
+review the diff.
+
+This is different from using Pi as your LLM provider (`LLM_PROVIDER=pi`, see
+[LLM providers](/llm-providers)). There Pi is the reasoning engine; here Pi is the thing that
+actually changes code.
+
+<Warning>
+This is a **mutating** tool — it changes files on disk. It is **disabled by default**: it only
+becomes available to the agent when `PI_CODING_ENABLED=1`. Enable it only when you want OpenSRE to
+make code changes. It never commits, pushes, or opens a PR, so you always review the diff.
+</Warning>
+
+## Quick reference
+
+| Env var | What it does |
+| --- | --- |
+| `PI_CODING_ENABLED` | Opt-in switch. Set to `1` to make the tool available. Off by default. |
+| `PI_CODING_MODEL` | Optional Pi model in `provider/model` form (e.g. `anthropic/claude-haiku-4-5`). |
+| `PI_CODING_WORKSPACE` | Default repository path Pi edits. Defaults to the current directory. |
+| `PI_CODING_TIMEOUT_SECONDS` | Per-task timeout (default 600, clamped 60–1800). |
+| `PI_BIN` | Optional explicit path to the `pi` binary. |
+
+## Enable it
+
+1. Install and authenticate the Pi CLI (same binary/credentials as the Pi provider):
+   ```bash
+   npm i -g @earendil-works/pi-coding-agent
+   # then authenticate: run `pi` and use /login, or export a provider key such as GEMINI_API_KEY
+   ```
+2. Turn the tool on:
+   ```bash
+   export PI_CODING_ENABLED=1
+   export PI_CODING_MODEL=anthropic/claude-haiku-4-5   # optional
+   ```
+3. Confirm Pi is ready:
+   ```bash
+   uv run opensre doctor
+   ```
+
+## How it works
+
+When the tool runs, it:
+
+1. runs `pi` in headless mode inside the workspace with your task plus a fixed set of rules
+   (follow `AGENTS.md`, do not commit or push, do not run destructive git commands, preserve
+   unrelated changes, summarize what changed),
+2. lets Pi edit the files,
+3. returns `success`, a `summary`, the list of `changed_files`, and the `diff` (truncated if large).
+
+You review the diff and decide whether to keep, commit, or revert the changes.
+
+## Example
+
+Once enabled, the tool is available to the agent (investigation surface). Describe a scoped
+coding task, for example:
+
+```
+add input validation to parse_config() in config/loader.py
+```
+
+If the agent calls the tool, Pi edits `PI_CODING_WORKSPACE`, and you get back a summary and the
+diff to review. Nothing is committed. (The agent decides whether to call the tool; for a
+deterministic run, invoke `pi_coding_task` directly — see the tests.)
+
+## Notes
+
+- Nothing is committed or pushed. Opening a PR is out of scope for now.
+- It is **disabled by default**. Only when `PI_CODING_ENABLED=1` does the agent see it and get
+  to choose to call it — enable it deliberately, since it edits files.
+- If `PI_CODING_ENABLED` is unset, or the Pi CLI is missing or unauthenticated, the tool stays
+  unavailable and returns a clear message instead of running.