@alphacoder-v0/pi-loops 0.17.5 → 0.18.0

package/recipes/issue-loop/triage.md

@@ -0,0 +1,147 @@
+---
+name: issue-triage
+description: One run of the triage loop. Moves the repository's open issues through the label state machine (needs-triage → needs-info | ready-for-agent | ready-for-human | wontfix), verifies claims, writes agent briefs, and reports recommendations to the inbox.
+---
+
+# Triage: one run
+
+Autonomy: propose
+
+The line above is the installed autonomy level; `/recipe add` wrote it and a person may change it.
+- `propose`: you evaluate, verify, comment, and label `needs-triage` / `needs-info`. Moving an
+  issue to `ready-for-agent`, `ready-for-human` or `wontfix` is the maintainer's click; you
+  recommend it in the inbox.
+- `act`: additionally, you move a **reproduced bug** with a brief to `ready-for-agent` yourself,
+  and close an issue that is already implemented or a duplicate (with the comment). Enhancements
+  and rejections still wait for the maintainer.
+
+You are the triage loop. Nobody is watching. Everything you post on the tracker is read by people
+later, and your final reply is read by a program (the loop protocol at the end of your prompt).
+
+## The state machine
+
+Every open issue carries one **category** label (`bug` | `enhancement`) and exactly one **state**
+label:
+
+| state | meaning | who moves an issue out of it |
+|---|---|---|
+| *(none)* | never looked at | you → `needs-triage`, first sighting |
+| `needs-triage` | being evaluated | you → `needs-info`; maintainer → `ready-for-agent`, `ready-for-human`, `wontfix` |
+| `needs-info` | waiting on the reporter | you → `needs-triage` once the reporter has replied |
+| `ready-for-agent` | brief accepted, an agent may build it | the implement loop |
+| `ready-for-human` | needs a person | the person |
+| `agent-working`, `in-review`, `agent-blocked` | the implement loop's states | not yours to touch |
+| `wontfix` | closed, will not be actioned | — |
+
+**The tracker is the truth; your notes are a cache.** Read labels and comments fresh every run.
+Your notes carry only what the tracker cannot tell you: which comment timestamp you last handled
+per issue, so you do not re-triage or re-ask.
+
+Every comment you post starts with this line, on its own:
+
+```
+> *This was generated by AI during triage.*
+```
+
+## What to do
+
+**First, read `docs/agents/issue-tracker.md`.** It says which tracker this repository uses and how
+to list, read, comment, change state, claim and close. The `gh` commands in this playbook are the
+GitHub spelling; if the file describes local Markdown files, do each step the way it describes
+instead (the states and the checkpoints are the same).
+
+1. **List the work.** Open issues that are (a) unlabeled, (b) `needs-triage`, or (c) `needs-info`
+   with a comment by someone other than you that is newer than the timestamp in your notes for
+   that issue. Oldest first. Take at most **3** this run; the rest wait for the next one.
+
+   ```sh
+   gh issue list --state open --limit 200 --json number,title,labels,updatedAt,author
+   gh issue view <n> --comments --json number,title,body,labels,author,createdAt,comments
+   ```
+
+2. **For each issue, gather context.** Read the whole issue and every comment; parse any earlier
+   *Triage Notes* or *Agent Brief* of yours so nothing already settled is asked again. Then:
+   - **Redundancy:** search the codebase for an existing implementation of the request — by the
+     concept, not the reporter's words — and remember where you looked.
+   - **Prior rejection:** read every `.out-of-scope/*.md` in the repository (if the directory
+     exists) and note any that resembles this request.
+   - **Duplicates:** compare against the other open issues' titles.
+
+3. **Verify the claim.** For a bug, reproduce it from the reporter's steps: run the command, the
+   test, the script. For an enhancement, confirm it is not already there. Record what happened:
+   confirmed (with the code path), not reproduced, or not enough detail to try.
+
+4. **Apply the outcome.**
+   - **Fully specified and verified** → post an *Agent Brief* (template below), make sure the
+     labels are `needs-triage` plus the category, and report to the inbox:
+     `#<n> brief posted — recommend ready-for-agent (<category>, <verified how>)`.
+   - **Needs a person** (design decision, external access, manual testing, taste) → post the brief
+     anyway with a line saying why it cannot be delegated; recommend `ready-for-human`.
+   - **Not enough to act on** → post *Triage Notes* (template below) with specific questions,
+     move to `needs-info`, report: `#<n> → needs-info (asked: <one phrase per question>)`.
+   - **Already implemented** → say where it lives in a comment; recommend `wontfix (already
+     implemented)`. Do not write to `.out-of-scope/`.
+   - **Out of scope / duplicate** → a polite comment with the reason (and the earlier issue, or
+     the `.out-of-scope/` file it matches); recommend `wontfix` or `duplicate of #<m>`.
+   - **Reporter replied on a `needs-info` issue** → move it back to `needs-triage` and evaluate
+     it again from step 2 in this same run.
+
+   Labels: `gh issue edit <n> --add-label "<state>" --remove-label "<old state>"`. Never leave an
+   issue with two state labels. Under `propose`, never close an issue.
+
+5. **Do not** edit code, open branches, or touch issues in `ready-for-agent`, `agent-working`,
+   `in-review` or `agent-blocked` — those belong to the implement loop and the maintainer.
+
+## Agent Brief
+
+The brief is the contract the implement loop works from; the issue body and discussion are only
+context. Write it to survive weeks of unrelated change: name types, functions, commands and
+behaviour, never file paths or line numbers. Behavioural, not procedural. Acceptance criteria that
+can each be checked on their own. Say what is out of scope.
+
+```markdown
+> *This was generated by AI during triage.*
+
+## Agent Brief
+
+**Category:** bug / enhancement
+**Summary:** one line
+
+**Current behavior:** what happens now (for a bug: the broken behaviour, reproduced how)
+**Desired behavior:** what should happen, including edge cases and errors
+
+**Key interfaces:**
+- `TypeName` / `functionName()` / config shape: what changes and why
+
+**Acceptance criteria:**
+- [ ] specific, independently checkable
+- [ ] …
+
+**Out of scope:**
+- what must not change in this issue
+```
+
+## Triage Notes (needs-info)
+
+```markdown
+> *This was generated by AI during triage.*
+
+## Triage Notes
+
+**What we've established so far:**
+- …
+
+**What we still need from you (@reporter):**
+- a specific, answerable question
+```
+
+## Notes for the next run
+
+One line per open issue you have handled: `#<n> <state you left it in> last-comment=<ISO timestamp
+with offset> brief=yes|no`. Drop closed issues. Stay under 2000 characters — if you must cut, cut
+the oldest `needs-info` lines; the tracker still has everything.
+
+## Inbox
+
+One line per issue you acted on, in the shapes above. No issues needing attention → no inbox
+lines. A finding is a decision for the maintainer, so it carries the recommendation and the reason.

package/skills/pi-loops/SKILL.md

@@ -16,6 +16,7 @@ The user's pi has pi-loops installed. Prefer its tools over ad-hoc `sleep` loops
 | the findings must be double-checked before the user sees them | `cron_create` with `stateful: true, verify: true` (a second adversarial sub-agent reviews each finding) |
 | "when <condition> happens, do <action>" (a file appears, a PR merges, a build finishes) | `new_trigger` — condition + action, fires once unless the user asks for repeating |
 | a reminder in N minutes | `cron_create` with schedule `in 10m` |
+| run the project's issue tracker as a standing process (triage, build, review), or an experiment loop against a research contract | tell the user to run `/recipe list` and `/recipe add <name>` — a packaged set of loops installed with one confirmation; do not recreate it with `cron_create` |
 
 Never use `new_trigger` for time-based schedules; never use `cron_create` for conditions.
 

package/src/cli.ts

@@ -20,6 +20,7 @@ import { askHost, renderHostSnapshot } from "./host-control-channel.ts";
 import { liveHost, stopHost } from "./host-control.ts";
 import { type UiPrefs, readUiPrefs } from "./ui-prefs.ts";
 import { JobStore, defaultLoopsDir } from "./store.ts";
+import { AUTONOMY_LEVELS, type AutonomyLevel, INSTALL_ROOT, TRACKER_FILE, addLineFor, ensureExcluded, installDirFor, installFiles, installedRecipes, listRecipes, loadRecipe, planInstall, playbookFiles, readRecord, resolveRecipeRef } from "./recipe.ts";
 import { TriggerStore } from "./triggers.ts";
 import { PI_LOOPS_VERSION } from "./version.ts";
 import { stamp } from "./schedule.ts";
@@ -104,6 +105,10 @@ export const CLI_USAGE = [
 	"",
 	"pi-loops host status | abort <run-id|trace-id> | stop",
 	"    Look in on the background host that keeps the clock while no pi is open, or interrupt it.",
+	"",
+	"pi-loops recipe list | show <name|path> | add <name|path> [--cwd <dir>] [--level report|propose|act] [--overwrite]",
+	"    The packaged recipes; what one installs; copy its playbooks into a project (.agents/skills/<name>/).",
+	"    The setup script and the jobs need a pi open in the project: /recipe add <name> finds the copies and finishes.",
 ].join("\n");
 
 /**
@@ -239,6 +244,7 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 	if (command === "web" || command === "tui") return launch(argv, out);
 	if (command === "upgrade") return upgrade(flags.has("check"), out);
 	if (command === "install-launcher") return installLauncher(str("dir"), out);
+	if (command === "recipe") return recipeCommand(positional, { level: str("level"), overwrite: flags.has("overwrite") }, cwd, loopsDir, out);
 
 	if (command === "sessions") {
 		// `pickSession` refuses an unknown id, and there was no way to discover one.
@@ -375,7 +381,66 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 	return asked ? 2 : 0;
 }
 
-const SUBCOMMANDS = new Set(["export", "import", "sessions", "inspect", "host", "web", "upgrade", "install-launcher", "help"]);
+const SUBCOMMANDS = new Set(["export", "import", "sessions", "inspect", "host", "recipe", "web", "upgrade", "install-launcher", "help"]);
+
+/**
+ * `pi-loops recipe`: the deterministic part of `/recipe`, for a shell with no pi open. `add` copies
+ * the playbooks, lists the directory in `.git/info/exclude` and writes the record — and stops there:
+ * the setup script is shown to a person before it runs and the jobs are created after a
+ * confirmation, both of which need the pi that `/recipe add` runs in. It finds the copies in place.
+ */
+async function recipeCommand(positional: string[], opts: { level?: string; overwrite: boolean }, cwd: string, loopsDir: string, out: (line: string) => void): Promise<number> {
+	const sub = positional[0] ?? "list";
+	if (sub === "list") {
+		const packaged = listRecipes();
+		const installed = new Map(installedRecipes(cwd).map((r) => [r.recipe, r]));
+		const jobs = new JobStore(loopsDir).load().filter((j) => j.recipe && j.cwd === cwd);
+		for (const r of packaged) {
+			const rec = installed.get(r.manifest.name);
+			const n = jobs.filter((j) => j.recipe === r.manifest.name).length;
+			out(`${r.manifest.name.padEnd(17)} ${(rec ? `installed: ${rec.level}, ${n} job(s)` : "—").padEnd(28)} ${r.manifest.summary}`);
+		}
+		for (const rec of installed.values()) if (!packaged.some((r) => r.manifest.name === rec.recipe)) out(`${rec.recipe.padEnd(17)} installed from ${rec.source} (${rec.level})`);
+		if (!packaged.length && !installed.size) out("no recipes packaged, none installed here");
+		return 0;
+	}
+	if (sub === "show" || sub === "add") {
+		const ref = positional[1];
+		if (!ref) throw new Error(`recipe ${sub} needs a recipe name or a directory`);
+		const resolved = resolveRecipeRef(ref, { cwd });
+		const recipe = loadRecipe(resolved.dir);
+		const m = recipe.manifest;
+		const rel = path.join(INSTALL_ROOT, m.name);
+		if (sub === "show") {
+			out(`${m.name} (${recipe.dir})`);
+			out(`  ${m.summary}`);
+			out(`  levels: ${m.levels.join(", ")}   tracker: ${m.needsTracker ? "needs docs/agents/issue-tracker.md" : "not needed"}${m.setup ? `   setup: ${m.setup}` : ""}`);
+			out(`  files → ${rel}/: ${playbookFiles(m).join(", ")}`);
+			for (const j of m.jobs) out(`  /cron add ${addLineFor(j, rel)}`);
+			const record = readRecord(installDirFor(cwd, m.name));
+			if (record) out(`  installed in ${cwd}: ${record.level}, ${record.installedAt}, pi-loops ${record.version}`);
+			return 0;
+		}
+		let level = m.levels[0];
+		if (opts.level) {
+			if (!m.levels.includes(opts.level as AutonomyLevel)) throw new Error(`${m.name} supports ${m.levels.join(", ")}, not "${opts.level}" (levels are ${AUTONOMY_LEVELS.join(", ")})`);
+			level = opts.level as AutonomyLevel;
+		}
+		const plan = planInstall(recipe, cwd, level);
+		const record = installFiles(recipe, cwd, level, { overwrite: opts.overwrite, source: resolved.source });
+		const excluded = ensureExcluded(cwd, rel);
+		if (m.needsTracker && fs.existsSync(path.join(cwd, TRACKER_FILE))) ensureExcluded(cwd, TRACKER_FILE, "file");
+		out(`copied ${record.files.length} file(s) → ${plan.targetDir}/ (level ${level}${opts.level ? "" : ", the lowest; --level to choose"})`);
+		for (const f of plan.changed) out(`  ${f}: ${opts.overwrite ? "overwritten" : "kept as edited (--overwrite replaces it)"}`);
+		out(excluded === "no-git" ? "not a git repository: nothing to exclude" : `.git/info/exclude: ${excluded === "added" ? "added" : "already listed"}`);
+		if (m.needsTracker && !fs.existsSync(path.join(cwd, TRACKER_FILE))) out(`${m.name} reads docs/agents/issue-tracker.md and this project has none: /recipe add ${m.name} in pi writes it with you first`);
+		out(`no jobs created: open pi in ${cwd} and run /recipe add ${m.name} — it shows ${m.setup ? `${m.setup} and ` : ""}these lines, then creates them:`);
+		for (const line of plan.addLines) out(`  /cron add ${line}`);
+		return 0;
+	}
+	out(`unknown recipe command ${JSON.stringify(sub)}: pi-loops recipe list | show <name|path> | add <name|path>`);
+	return 2;
+}
 
 /** `v1.2.3` → comparable parts; anything else is not a release and is ignored. */
 function semver(tag: string): [number, number, number] | undefined {

package/src/extension-entry.ts

@@ -0,0 +1,24 @@
+/**
+ * What pi loads (`pi.extensions` in package.json): a version check, then the extension.
+ *
+ * The check cannot sit in `src/pi-loops.ts`. That file and the modules under it import names pi
+ * did not always export (`ModelRuntime`, `readStoredCredential`, `createSyntheticSourceInfo`) and
+ * subscribe to events it did not always emit. ESM links a whole import graph before running a line
+ * of it, so on an older pi the failure is a link error naming one export — "does not provide an
+ * export named ModelRuntime" — and nothing in it says "your pi is too old". This file imports only
+ * what every pi has exported for a long time, reads the version, and imports the rest afterwards,
+ * so what an old pi prints is the sentence that says which pi it needs.
+ *
+ * A namespace import on purpose: a name missing from an old pi is then `undefined` rather than a
+ * link error, which is exactly the case the check exists for.
+ */
+import * as sdk from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { piTooOld } from "./pi-floor.ts";
+
+export default async function (pi: ExtensionAPI) {
+	const refusal = piTooOld(sdk.VERSION);
+	if (refusal) throw new Error(refusal);
+	const { default: piLoops } = await import("./pi-loops.ts");
+	return piLoops(pi);
+}

package/src/pi-floor.ts

@@ -0,0 +1,37 @@
+/**
+ * The oldest pi this extension loads into. `src/extension-entry.ts` reads it before anything else
+ * is imported, both READMEs state it, and `test/pi-floor.test.ts` keeps the three the same.
+ *
+ * 0.84.3 is where the API this code is written against became complete: `session_compact_failed`
+ * arrived there, `ModelRuntime` and `readStoredCredential` in 0.80.8, `ctx.thinkingLevel` in
+ * between. It was found by type-checking `src/` against older releases rather than by reading
+ * changelogs — 0.80.8 fails on the two newest names, 0.84.3 passes clean — and it is the version
+ * to re-check the same way when a newer name is used. Nothing enforces it at install time: pi
+ * installs packages with `--legacy-peer-deps`, so `peerDependencies` stays `*` as pi's docs ask
+ * and the range there would not be read anyway.
+ */
+export const PI_MIN_VERSION = "0.84.3";
+
+/** `[major, minor, patch]`, or undefined for anything that does not start `N.N.N` (a `v` in front is fine). */
+function parse(version: string): [number, number, number] | undefined {
+	const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+	return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+
+/**
+ * Why this pi cannot load pi-loops, as the one sentence pi prints after "Failed to load extension",
+ * or undefined when it can. A pi that reports no version is refused as well: every pi new enough
+ * to load this exports `VERSION`, so a missing one is an old one, not an unknown one.
+ */
+export function piTooOld(version: string | undefined, min: string = PI_MIN_VERSION): string | undefined {
+	const have = version === undefined ? undefined : parse(version);
+	const need = parse(min);
+	if (!need) throw new Error(`PI_MIN_VERSION is not a version: ${JSON.stringify(min)}`);
+	const upgrade = "upgrade pi (`pi update`, or `npm i -g @earendil-works/pi-coding-agent`)";
+	if (!have) return `pi-loops needs pi ${min} or newer and this pi reports ${version === undefined ? "no version" : `version ${JSON.stringify(version)}`}: ${upgrade}`;
+	for (let i = 0; i < 3; i++) {
+		if (have[i] > need[i]) return undefined;
+		if (have[i] < need[i]) return `pi-loops needs pi ${min} or newer and this is pi ${version}: ${upgrade}`;
+	}
+	return undefined;
+}