omp-auto-loop 0.1.1

package/README.md

@@ -0,0 +1,50 @@
+# 🔄 Agent Loop
+
+General-purpose loop extension for pi. Repeats agent turns automatically in three modes: until a goal is met, for a fixed number of passes, or through a sequence of named pipeline stages.
+
+## Install
+
+```bash
+pi install npm:pi-agent-loop
+```
+
+## What it does
+
+Registers a `/loop` command and a `loop_control` tool. On each iteration, the agent does its work then calls `loop_control` to either advance to the next iteration (`next`) or declare the goal complete (`done`). The loop context is injected into the system prompt automatically so the agent always knows where it is.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/loop goal <description>` | Repeat until the LLM declares the goal met (open-ended) |
+| `/loop passes <N> <task>` | Run exactly N passes |
+| `/loop pipeline <s1\|s2\|s3> <goal>` | Run named stages sequentially, stop after the last |
+| `/loop-stop` | Stop the active loop immediately |
+
+## Shortcut
+
+| Shortcut | Description |
+|---|---|
+| `Ctrl+Shift+X` | Emergency abort — stops the loop and cancels the current turn |
+
+## Tool: `loop_control`
+
+The LLM calls this tool to signal progress. It is only active during a loop.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `status` | `"next" \| "done"` | Advance to next iteration or declare completion |
+| `summary` | `string` | Brief summary of what was accomplished this iteration |
+| `reason` | `string?` | Why the goal is met (used with `"done"`) |
+
+## Examples
+
+```
+/loop goal Refactor all test files to use the new assertion API
+/loop passes 3 Review and improve the README
+/loop pipeline analyze|implement|test Write and test the new auth module
+```
+
+## TUI widget
+
+While a loop is active, a status bar entry and widget show the current mode, goal, and iteration count.

package/index.ts

@@ -0,0 +1,116 @@
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { Key } from "@oh-my-pi/pi-tui";
+import { buildPrompt, emptyState, getSystemPromptAddition, type LoopState, updateWidget } from "./state.js";
+import { getLoopControlToolDefinition, handleLoopControlTool, renderLoopControlCall, renderLoopControlResult } from "./tool.js";
+
+export default function (pi: ExtensionAPI) {
+	let state = emptyState();
+
+	const reconstruct = (ctx: ExtensionContext) => {
+		state = emptyState();
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolName === "loop_control") {
+				const d = entry.message.details as LoopState | undefined;
+				if (d) state = { ...d };
+			}
+		}
+	};
+
+	pi.on("session_start", async (_e, ctx) => reconstruct(ctx));
+	pi.on("session_switch", async (_e, ctx) => reconstruct(ctx));
+	pi.on("session_fork", async (_e, ctx) => reconstruct(ctx));
+	pi.on("session_tree", async (_e, ctx) => reconstruct(ctx));
+
+	pi.on("input", async (event, ctx) => {
+		const text = event.text.trim();
+		// Handle commands natively
+		if (text.startsWith("/")) {
+			if (text.startsWith("/once ") || text === "/once") {
+				return { text: text.slice(5).trim() };
+			}
+			return {};
+		}
+
+		// Normal message: start loop
+		state = { active: true, currentStep: 0, goal: text, done: false, reasonDone: "" };
+		updateWidget(state, ctx);
+
+		// Delay the prompt steer delivery to avoid conflicting with the pending user message
+		setTimeout(() => {
+			pi.sendMessage({ customType: "loop-iteration", content: buildPrompt(state), display: false }, { triggerTurn: false, deliverAs: "steer" });
+		}, 50);
+
+		return {}; // let original text through
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (!state.active) return;
+		return { systemPrompt: event.systemPrompt + getSystemPromptAddition(state) };
+	});
+
+	pi.on("turn_end", async (_e, ctx) => {
+		if (!state.active) return;
+
+		if (state.confirmingDone) {
+			state.active = false;
+			state.done = true;
+			state.reasonDone = "Confirmed complete by skipping loop_control";
+			state.confirmingDone = false;
+			updateWidget(state, ctx);
+			return;
+		}
+
+		if (state.nextScheduled) {
+			state.nextScheduled = false;
+			return;
+		}
+
+		// Fallback: LLM stopped without calling loop_control or confirming done
+		state.currentStep++;
+		updateWidget(state, ctx);
+		setTimeout(() => {
+			pi.sendMessage({
+				customType: "loop-fallback",
+				content: "You stopped without calling `loop_control`. If the task is incomplete, continue working. If done, call `loop_control` with status 'done'.",
+				display: false
+			}, { triggerTurn: true, deliverAs: "steer" });
+		}, 100);
+	});
+
+	pi.registerTool({
+		...getLoopControlToolDefinition(),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const result = handleLoopControlTool({ params, state, pi, ctx });
+			state = result.newState;
+			updateWidget(state, ctx);
+			return { content: result.content, details: result.details };
+		},
+		renderCall: renderLoopControlCall as any,
+		renderResult: renderLoopControlResult as any,
+	});
+
+	const stopLoop = (ctx: ExtensionContext, reason: string) => {
+		if (!state.active) {
+			ctx.ui.notify("No active loop", "info");
+			return;
+		}
+		state.active = false;
+		state.done = true;
+		state.reasonDone = reason;
+		updateWidget(state, ctx);
+		ctx.ui.notify(`Loop stopped after ${state.currentStep + 1} iteration(s)`, "warning");
+	};
+
+	pi.registerCommand("loop-stop", {
+		description: "Stop the active loop",
+		handler: async (_args, ctx) => stopLoop(ctx, "Stopped by user"),
+	});
+
+	pi.registerShortcut(Key.ctrlShift("x"), {
+		description: "Stop the active loop",
+		handler: async (ctx) => {
+			stopLoop(ctx, "Stopped by shortcut");
+			ctx.abort();
+		},
+	});
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "omp-auto-loop",
+	"version": "0.1.1",
+	"description": "General-purpose agent loop extension for pi. Supports goal loops (repeat until done), fixed-pass loops, and multi-stage pipelines via /loop goal, /loop passes, and /loop pipeline commands.",
+	"keywords": [
+		"pi-package"
+	],
+	"license": "MIT",
+	"pi": {
+		"extensions": [
+			"."
+		]
+	},
+	"peerDependencies": {
+		"@oh-my-pi/pi-coding-agent": "*"
+	}
+}

package/state.ts

@@ -0,0 +1,50 @@
+import type { ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+
+export interface LoopState {
+        active: boolean;
+        currentStep: number;
+        goal: string;
+        done: boolean;
+        reasonDone: string;
+        confirmingDone?: boolean;
+        nextScheduled?: boolean;
+}
+
+export function emptyState(): LoopState {
+        return { active: false, currentStep: 0, goal: "", done: false, reasonDone: "", confirmingDone: false, nextScheduled: false };
+}
+
+export function buildPrompt(state: LoopState): string {
+        return [
+                `## Loop — Iteration ${state.currentStep + 1}`,
+                `Goal: ${state.goal}`,
+                `Work toward the goal. When the goal is fully met, call loop_control with status "done" and explain why.`,
+                `If more work is needed, call loop_control with status "next" describing what's left.`,
+        ].join("\n");
+}
+
+export function updateWidget(state: LoopState, ctx: ExtensionContext) {
+        if (!state.active) {
+                ctx.ui.setStatus("loop", undefined);
+                ctx.ui.setWidget("loop", undefined);
+                return;
+        }
+        const label = `iteration ${state.currentStep + 1}`;
+        ctx.ui.setStatus("loop", `🔄 ${label}`);
+        ctx.ui.setWidget("loop", [
+                `┌─ Loop ──────────`,
+                `│ ${label}`,
+                `└─ Ctrl+Shift+X to stop ─`,
+        ]);
+}
+
+export function getSystemPromptAddition(state: LoopState): string {
+        return [
+                "",
+                "## Active Loop",
+                `Step: ${state.currentStep + 1}`,
+                `Goal: ${state.goal}`,
+                "You MUST call `loop_control` when you finish your work for this iteration.",
+                'Use status "next" to advance or "done" when the goal is fully met.',
+        ].join("\n");
+}

package/tool.ts

@@ -0,0 +1,68 @@
+import { StringEnum } from "@oh-my-pi/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { Text } from "@oh-my-pi/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { buildPrompt, type LoopState } from "./state.js";
+
+export function handleLoopControlTool(opts: {
+        params: { status: "next" | "done"; summary: string; reason?: string };
+        state: LoopState;
+        pi: ExtensionAPI;
+        ctx: ExtensionContext;
+}): { content: any[]; details?: LoopState; newState: LoopState } {
+        const { params, state, pi } = opts;
+        if (!state.active) {
+                return { content: [{ type: "text", text: "No active loop." }], newState: state };
+        }
+
+        if (params.status === "done") {
+                if (!state.confirmingDone) {
+                        const newState = { ...state, confirmingDone: true };
+                        return {
+                                content: [{ type: "text", text: "Please confirm that the work is completely done. If there are still pending tasks, call loop_control with status 'next'. If you are truly done, just finish your response without calling loop_control again." }],
+                                details: { ...newState },
+                                newState,
+                        };
+                }
+                const newState = { ...state, done: true, reasonDone: params.reason ?? params.summary, active: false, confirmingDone: false };
+                return {
+                        content: [{ type: "text", text: `✓ Loop complete after ${state.currentStep + 1} iteration(s). Reason: ${newState.reasonDone}` }],
+                        details: { ...newState },
+                        newState,
+                };
+        }
+
+        const newState = { ...state, currentStep: state.currentStep + 1, confirmingDone: false, nextScheduled: true };
+        setTimeout(() => {
+                pi.sendMessage({ customType: "loop-iteration", content: buildPrompt(newState), display: false }, { triggerTurn: true, deliverAs: "steer" });
+        }, 100);
+
+        return {
+                content: [{ type: "text", text: `→ Advancing to step ${newState.currentStep + 1}. Summary: ${params.summary}` }],
+                details: { ...newState },
+                newState,
+        };
+}
+
+export function getLoopControlToolDefinition() {
+        return {
+                name: "loop_control",
+                label: "Loop Control",
+                description: "Signal loop progress. Call this when you finish a loop iteration. status 'next' to advance, 'done' to finish.",
+                parameters: Type.Object({
+                        status: StringEnum(["next", "done"] as const),
+                        summary: Type.String({ description: "Brief summary of what was accomplished this iteration" }),
+                        reason: Type.Optional(Type.String({ description: "Why the goal is met (for 'done')" })),
+                }),
+        };
+}
+
+export function renderLoopControlCall(args: { status: string }, theme: any) {
+        return new Text(theme.fg("toolTitle", theme.bold("loop_control ")) + theme.fg(args.status === "done" ? "success" : "accent", args.status), 0, 0);
+}
+
+export function renderLoopControlResult(result: { details?: LoopState }, _opts: unknown, theme: any) {
+        const d = result.details;
+        if (!d) return new Text("", 0, 0);
+        return new Text(theme.fg(d.done ? "success" : "accent", `${d.done ? "✓" : "→"} step ${d.currentStep + 1}`), 0, 0);
+}