@dumbmice/pi-todo-loop 0.0.0-stage → 0.1.1

package/src/config.ts

@@ -0,0 +1,48 @@
+/**
+ * Config loading. A missing, unreadable, or malformed file falls back to the
+ * defaults: this extension must never be the reason a turn fails.
+ */
+
+import { readFileSync } from "node:fs";
+import { DEFAULTS, type LoopConfig } from "./loop.ts";
+
+export { DEFAULTS };
+
+function coerce(raw: unknown): Partial<LoopConfig> {
+	if (typeof raw !== "object" || raw === null) return {};
+	const record = raw as Record<string, unknown>;
+	const out: Partial<LoopConfig> = {};
+
+	// Clamped, not just validated: a hostile or typo'd config must not be able to
+	// defeat the caps it configures (`maxRounds: 1e9` would otherwise be honoured).
+	const bounded = (value: unknown, ceiling: number): number | undefined =>
+		typeof value === "number" && Number.isFinite(value) && value >= 1
+			? Math.min(Math.floor(value), ceiling)
+			: undefined;
+
+	const maxRounds = bounded(record.maxRounds, 1_000);
+	if (maxRounds !== undefined) out.maxRounds = maxRounds;
+
+	const maxStrikes = bounded(record.maxStrikes, 100);
+	if (maxStrikes !== undefined) out.maxStrikes = maxStrikes;
+
+	if (typeof record.injectState === "boolean") out.injectState = record.injectState;
+
+	const maxInjectedTasks = bounded(record.maxInjectedTasks, 50);
+	if (maxInjectedTasks !== undefined) out.maxInjectedTasks = maxInjectedTasks;
+
+	return out;
+}
+
+export function mergeConfig(raw: unknown): LoopConfig {
+	return { ...DEFAULTS, ...coerce(raw) };
+}
+
+export function loadConfig(path: string): LoopConfig {
+	try {
+		return mergeConfig(JSON.parse(readFileSync(path, "utf8")));
+	} catch {
+		// A fresh copy: the shared object must never be mutable by a caller.
+		return { ...DEFAULTS };
+	}
+}

package/src/index.ts

@@ -0,0 +1,323 @@
+/**
+ * @dumbmice/pi-todo-loop — continuation driven by an rpiv-todo list.
+ *
+ * Pairs with `@juicesharp/rpiv-todo`; does not import or patch it. Three hooks:
+ *
+ *   context    append the live open-task list at the tail (never persisted),
+ *              replacing a trailing marker so the request never ends user → user
+ *   turn_end   request another turn while tasks are open, bounded by
+ *              maxRounds / maxStrikes (see loop.ts)
+ *   /todoloop  status | pause | resume | reset
+ *
+ * Architecture notes worth keeping in mind when changing this file:
+ *
+ *   - A `turn_end` continuation must leave the final message role != assistant,
+ *     so one entry is mandatory (`_buildBoundaryContext().canContinue` in pi
+ *     1.5.0). We append a `custom_message` with `display: false`.
+ *   - Markers are never removed from history: they sit between assistant turns and
+ *     are what keep the conversation alternating. A marker at the tail is replaced
+ *     by the state block, so the request ends on exactly one user message.
+ *   - pi's non-assistant requirement binds the *persisted projection* checked at
+ *     `turn_end`, not the provider request (register item 3).
+ *   - The marker customType is deliberately stable: sessions created by earlier
+ *     builds keep filtering correctly.
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadConfig } from "./config.ts";
+import { renderInjection } from "./inject.ts";
+import { decide, initialState, type LoopState } from "./loop.ts";
+import { readSnapshot } from "./state.ts";
+
+/**
+ * Snapshot of the pi extension API surface this file depends on. Keep in step
+ * with the header of `docs/pi-api-alignment.md`.
+ *
+ * No pi type import on purpose: the extension is loaded by pi and the type
+ * package would otherwise need to be a dependency, for one signature.
+ */
+export const PI_API_SNAPSHOT = "1.5.0";
+
+/** The part of `ExtensionContext` this extension reads. */
+interface SessionContext {
+	readonly cwd: string;
+	readonly sessionManager: { getBranch(): readonly unknown[] };
+	readonly ui: { notify(message: string, level: "info" | "error" | "warning"): void };
+}
+
+/** Stable across versions: the tail check must keep recognising markers from earlier builds. */
+export const MARKER_TYPE = "todo-loop:continue";
+
+/**
+ * Constant body. The marker keeps the persisted history alternating and gives
+ * `turn_end` a non-assistant tail; it carries no counters, so a stale marker in
+ * history cannot claim the loop is on some other round. It states the instruction
+ * because with `injectState: false` this line is the only text the model receives.
+ */
+export const MARKER_BODY =
+	"Continue with the open todo tasks. If the human's latest instruction says to stop or limits what to do, do that instead.";
+
+export const CONFIG_PATH = join(homedir(), ".pi/agent/todo-loop.json");
+const KILL_SWITCH_GLOBAL = join(homedir(), ".pi/agent/todo-loop-off");
+
+/**
+ * Overrides for tests and embedding. Production always uses the documented
+ * paths; nothing else in the extension varies.
+ */
+export interface TodoLoopOptions {
+	/** Replaces `~/.pi/agent/todo-loop.json`. */
+	configPath?: string;
+	/** Replaces `~/.pi/agent/todo-loop-off`. */
+	killSwitchGlobal?: string;
+	/** Replaces `.pi/todo-loop-off`, resolved against `ctx.cwd`. */
+	killSwitchLocal?: string;
+}
+
+function branchEntries(ctx: SessionContext): readonly unknown[] {
+	try {
+		return (ctx.sessionManager.getBranch() as readonly unknown[]) ?? [];
+	} catch {
+		return [];
+	}
+}
+
+export default function todoLoop(pi: any, options: TodoLoopOptions = {}): void {
+	const configPath = options.configPath ?? CONFIG_PATH;
+	const killSwitchGlobal = options.killSwitchGlobal ?? KILL_SWITCH_GLOBAL;
+	const killSwitchLocal = options.killSwitchLocal ?? ".pi/todo-loop-off";
+
+	const isDisabled = (ctx: SessionContext): boolean => {
+		try {
+			return existsSync(killSwitchGlobal) || existsSync(join(ctx.cwd, killSwitchLocal));
+		} catch {
+			// existsSync swallows ENOENT; anything else must not fail a turn.
+			return false;
+		}
+	};
+
+	const state: LoopState & { paused: boolean; reason: string; lastOpenCount: number } = {
+		...initialState(),
+		paused: false,
+		reason: "idle",
+		lastOpenCount: 0,
+	};
+
+	pi.on("context", async (event: any, ctx: SessionContext) => {
+		if (isDisabled(ctx) || state.paused) return undefined;
+		// A hook that rewrites an unknown payload into a one-message request is
+		// worse than doing nothing; leave the request alone.
+		if (!Array.isArray(event?.messages)) return undefined;
+
+		const original = event.messages as unknown[];
+		const config = loadConfig(configPath);
+		// No injection configured: nothing below needs the branch at all.
+		if (!config.injectState) return undefined;
+
+		const snapshot = readSnapshot(branchEntries(ctx));
+		const injecting = snapshot.open.length > 0;
+		if (!injecting) return undefined;
+
+		// The marker is persisted between assistant turns, so it is what keeps the
+		// history alternating: assistant → marker(user) → assistant. Stripping the
+		// historical ones would expose runs of consecutive assistant messages, which
+		// alternation-requiring providers reject. So markers stay in history; only a
+		// marker sitting at the tail (the continuation request about to be made) is
+		// replaced by the state block, so the request never ends on user → user.
+		const text = { type: "text", text: renderInjection(snapshot, config, { reconcile: state.rounds >= 1 }) };
+		const record = (message: unknown): Record<string, unknown> | null =>
+			typeof message === "object" && message !== null ? (message as Record<string, unknown>) : null;
+		const isMarker = (message: unknown): boolean => record(message)?.customType === MARKER_TYPE;
+		// pi projects every role except these to a user-role message in the request:
+		// `custom`, `bashExecution`, `branchSummary`, `compactionSummary`, and plain
+		// `user`. Anything else is user-role for the purpose of alternation, so the test
+		// is a whitelist of non-user roles — the direction that merges rather than
+		// appending a second user message.
+		const NON_USER_ROLES = new Set(["assistant", "toolResult", "system", "tool"]);
+		const isUserRole = (message: unknown): boolean => {
+			const role = record(message)?.role;
+			return typeof role === "string" && !NON_USER_ROLES.has(role);
+		};
+
+		// A marker only earns its place *between* two assistant turns, where it is the
+		// alternation glue. Anywhere else it is redundant bookkeeping that would sit
+		// next to a real user message and break alternation: drop it. That covers a
+		// marker at the tail, a marker followed by a human message, and two markers in
+		// a row.
+		const kept = (original as unknown[]).filter((message, index, list) => {
+			if (!isMarker(message)) return true;
+			const previous = list[index - 1];
+			const next = list[index + 1];
+			// Both neighbours must exist and neither may be user-role: `[A, M, H]` and
+			// `[A, H, M, A]` both leave a marker next to a human message, which is the
+			// adjacency this filter exists to prevent.
+			return previous !== undefined && next !== undefined && !isUserRole(previous) && !isUserRole(next);
+		});
+
+		// Nothing left to attach to: an empty request would be an instruction with no prompt.
+		if (kept.length === 0) return undefined;
+
+		const tail = kept[kept.length - 1];
+		const tailRole = record(tail)?.role;
+		// pi rebuilds the content of `bashExecution`, `branchSummary` and
+		// `compactionSummary` from their own fields and ignores `content`, so merging
+		// into one of those would silently drop the block. Only `user` and `custom`
+		// honour `content`; the others get a separate message.
+		const mergeable = tailRole === "user" || tailRole === "custom";
+		if (tail !== null && isUserRole(tail) && mergeable) {
+			// Merge into the human's own message rather than adding a second one after it.
+			const entry = tail as Record<string, unknown>;
+			const existing = Array.isArray(entry.content)
+				? (entry.content as unknown[])
+				: typeof entry.content === "string" && entry.content !== ""
+					? [{ type: "text", text: entry.content }]
+					: [];
+			const content = [...existing, text];
+			return { messages: [...kept.slice(0, -1), { ...entry, content }] };
+		}
+
+		return { messages: [...kept, { role: "user", content: [text], timestamp: Date.now() }] };
+	});
+
+	pi.on("turn_end", async (event: any, ctx: SessionContext) => {
+		if (isDisabled(ctx) || state.paused) return undefined;
+
+		const config = loadConfig(configPath);
+		const snapshot = readSnapshot(branchEntries(ctx));
+		const toolResults = Array.isArray(event?.toolResults) ? (event.toolResults as unknown[]) : [];
+		const toolResultCount = toolResults.length;
+		// `turn_end` fires for every assistant response, including one that ended in a
+		// tool call. Such a turn already causes pi's next request, so a continuation
+		// would be redundant — and counting it as a round spends the budget on work the
+		// loop did not cause. Only a settle (no tool results) can spend a round.
+		//
+		// A tool turn is still *work*, so it clears a pending strike: without this, a
+		// model that runs tools and never updates the list (the case this extension is
+		// for) collects two strikes across its settles and stops with "no progress"
+		// while it was working the whole time.
+		// A list that goes open -> clear in a turn whose only tool calls were `todo` is
+		// the loop's success state and its failure state at once. Never police it;
+		// just do not launder the trust: say so once.
+		if (snapshot.open.length === 0 && state.lastOpenCount > 0 && toolResultCount > 0) {
+			const names = toolResults.map((result) => String((result as Record<string, unknown>)?.toolName ?? ""));
+			const onlyTodo = names.every((name) => name === "todo");
+			if (onlyTodo) {
+				ctx.ui?.notify?.(
+					"todo-loop: the list was cleared by todo calls alone in that turn — no other tool work accompanied it",
+					"warning",
+				);
+			}
+		}
+		state.lastOpenCount = snapshot.open.length;
+
+		if (toolResultCount > 0) {
+			if (String(event?.outcome) !== "completed") {
+				state.reason = `stopped: turn outcome was ${String(event?.outcome)}`;
+				return undefined;
+			}
+			state.strikes = 0;
+			return undefined;
+		}
+
+		const decision = decide({
+			outcome: String(event?.outcome),
+			toolResultCount,
+			signature: snapshot.signature,
+			openCount: snapshot.open.length,
+			taskCount: snapshot.tasks.length,
+			anchor: snapshot.anchor,
+			state,
+			config,
+		});
+
+		if (!decision.continue) {
+			const previous = state.reason;
+			Object.assign(state, decision.next, { reason: decision.reason });
+			// A stop is otherwise silent until someone runs /todoloop.
+			if (previous !== decision.reason) ctx.ui?.notify?.(`todo-loop: ${decision.reason}`, "info");
+			return undefined;
+		}
+
+		// Build the proposal before committing the counters: a throw here (or a
+		// proposal pi rejects) must not leave `/todoloop` reporting a round that
+		// never happened.
+		const entries = Array.isArray(event?.entries) ? (event.entries as unknown[]) : [];
+		const next = decision.next;
+		const proposal = {
+			continue: true,
+			entries: [
+				...entries,
+				{
+					type: "custom_message",
+					customType: MARKER_TYPE,
+					content: MARKER_BODY,
+					display: false,
+				},
+			],
+		};
+
+		Object.assign(state, next, { reason: decision.reason });
+		return proposal;
+	});
+
+	pi.registerCommand("todoloop", {
+		description: "Show or control the todo-driven continuation loop",
+		handler: async (args: string, ctx: SessionContext) => {
+			const raw = (args ?? "").trim();
+			const [command, ...rest] = raw.toLowerCase().split(/\s+/);
+			const config = loadConfig(configPath);
+
+			if (command === "pause") {
+				state.paused = true;
+				state.reason = "paused by user";
+				ctx.ui?.notify?.("todo-loop: paused in this session", "info");
+				return;
+			}
+			if (command === "resume") {
+				state.paused = false;
+				state.reason = "resumed by user";
+				ctx.ui?.notify?.("todo-loop: resumed", "info");
+				return;
+			}
+			if (command === "reset") {
+				Object.assign(state, initialState(), { paused: state.paused, reason: "counters reset" });
+				ctx.ui?.notify?.("todo-loop: counters reset", "info");
+				return;
+			}
+
+			if (command !== "" && !["status", "pause", "resume", "reset"].includes(command)) {
+				ctx.ui?.notify?.(
+					`todo-loop: unknown argument "${command}"; use status, pause, resume or reset`,
+					"warning",
+				);
+			} else if (rest.length > 0) {
+				ctx.ui?.notify?.(
+					`todo-loop: ignoring extra arguments "${rest.join(" ")}"; use status, pause, resume or reset`,
+					"warning",
+				);
+			}
+
+			const snapshot = readSnapshot(branchEntries(ctx));
+			const mode = isDisabled(ctx)
+				? "DISABLED (kill-switch present)"
+				: state.paused
+					? "PAUSED"
+					: state.reason.startsWith("stopped:")
+						? "stopped (next human message starts a new budget)"
+						: "active";
+			ctx.ui?.notify?.(
+				[
+					`todo-loop ${mode}`,
+					`rounds ${state.rounds}/${config.maxRounds} · strikes ${state.strikes}/${config.maxStrikes}`,
+					`open ${snapshot.open.length}/${snapshot.tasks.length} tracked · inject ${config.injectState ? "on" : "off"}`,
+					`anchor ${snapshot.anchor || "(none)"}`,
+					`last: ${state.reason}`,
+					`config ${configPath}`,
+				].join("\n"),
+				"info",
+			);
+		},
+	});
+}
+

package/src/inject.ts

@@ -0,0 +1,97 @@
+/**
+ * The state injection.
+ *
+ * Appended at the tail of every request by the `context` hook and never
+ * persisted. Two properties matter:
+ *
+ *   - It is the *whole* open list (bounded), not a hint to call `list`. After
+ *     compaction the model has no other way to learn the list still exists.
+ *   - It is a user-role block appended at the tail, replacing a trailing
+ *     continuation marker so the request never ends on two user-role messages.
+ */
+
+import type { LoopConfig } from "./loop.ts";
+import type { Snapshot } from "./state.ts";
+
+export const INJECT_TAG = "todo_loop_state";
+
+function label(status: string, subject: string, activeForm?: string): string {
+	if (status === "in_progress" && activeForm) return activeForm;
+	return subject || "(untitled)";
+}
+
+/**
+ * One line of model-authored text, rendered inside a tag at the end of a request.
+ *
+ * A task subject is written by the model, possibly from a fetched page or a repo
+ * file, so it must not be able to: close the tag (`</`), start a new line that reads
+ * like one of our own directives, or push the block to an unbounded size.
+ */
+export function sanitizeLabel(text: string): string {
+	// Every Unicode line terminator, not just \n: U+2028/9 and NEL (U+0085) split a
+	// line for some readers, which is the channel this function exists to close.
+	const flattened = text.replace(/[\r\n\t\u2028\u2029\u0085]+/g, " ");
+	// C0/C1 controls, bidi overrides and isolates, zero-width and BOM characters: a
+	// NUL can break JSON encoding and a bidi override can visually reverse a line.
+	const cleaned = flattened.replace(
+		/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g,
+		"",
+	);
+	// No tag can be opened or closed from task text: `<` is escaped, which also covers
+	// `</` and a bare `<todo_loop_state>` that would invert the block's nesting.
+	const escaped = cleaned.replaceAll("<", "&lt;").replaceAll("&lt;", "&lt;");
+	// Bound the working set before materialising code points (a 1 MB subject would
+	// otherwise allocate a 1M-element array per row); 480 UTF-16 units can hold far
+	// more than the 120 code points that survive.
+	const bounded = escaped.length > 480 ? escaped.slice(0, 480) : escaped;
+	// By code point, never UTF-16 units: `slice` can cut a surrogate pair in half and
+	// leave a lone surrogate in the request.
+	const points = Array.from(bounded).slice(0, 120).join("");
+	// An unpaired surrogate already in the payload survives `Array.from`; drop it so the
+	// request is always valid UTF-16.
+	return points.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "").trim();
+}
+
+export interface InjectionOptions {
+	/**
+	 * Add the reconciliation clause. Off for the first nudge of a chain, on afterwards:
+	 * handing a model an explicit "fix the list" instruction on its first sighting
+	 * invites it to reshape the list instead of doing the work, while after one nudge a
+	 * drifted list is the likelier explanation.
+	 */
+	reconcile?: boolean;
+}
+
+const RECONCILE_CLAUSE = [
+	"If this list has drifted from the work, reconcile it now: update statuses,",
+	"add what is missing, and remove what no longer applies.",
+].join("\n");
+
+export function renderInjection(
+	snapshot: Snapshot,
+	config: LoopConfig,
+	options: InjectionOptions = {},
+): string {
+	const shown = snapshot.open.slice(0, config.maxInjectedTasks);
+	const rows = shown.map(
+		(task) =>
+			`  ${task.id}. [${sanitizeLabel(task.status)}] ${sanitizeLabel(
+				label(task.status, task.subject, task.activeForm),
+			)}`,
+	);
+	const hidden = snapshot.open.length - shown.length;
+
+	return [
+		`<${INJECT_TAG}>`,
+		`${snapshot.open.length} tracked task(s) are still open on this branch:`,
+		...rows,
+		...(hidden > 0 ? [`  ... and ${hidden} more`] : []),
+		"The human's latest message outranks everything above: if it says to stop, to wait,",
+		"or limits what to do, do that instead and say so in one line. Otherwise carry on",
+		"with the open tasks, and move a task to in_progress when you start it and to",
+		"completed only once it is actually verified — if a task cannot be verified now,",
+		"leave it open and say what is blocking it.",
+		...(options.reconcile ? [RECONCILE_CLAUSE] : []),
+		`</${INJECT_TAG}>`,
+	].join("\n");
+}

package/src/loop.ts

@@ -0,0 +1,131 @@
+/**
+ * Loop policy: the pure decision function.
+ *
+ * Everything that can loop forever lives here, so it can be unit-tested without
+ * running a model. `index.ts` only adapts pi events into `DecisionInput` and
+ * applies the result.
+ */
+
+export interface LoopState {
+	/** Continuations started since the last human message. */
+	rounds: number;
+	/** Consecutive turns that neither ran a tool nor changed the task list. */
+	strikes: number;
+	/** Task signature at the previous decision, to detect list changes. */
+	lastSignature: string;
+	/** Settles since the list last changed: a stale list stops on the cap, not on strikes. */
+	staleSettles: number;
+	/** Id of the user message the current budget belongs to. */
+	anchor: string;
+}
+
+export interface LoopConfig {
+	/** Max consecutive auto-continuations per human message. */
+	maxRounds: number;
+	/** Consecutive no-progress turns tolerated before stopping. */
+	maxStrikes: number;
+	/** Inject the live task list at the tail of every request. */
+	injectState: boolean;
+	/** Max open tasks rendered in that injection. */
+	maxInjectedTasks: number;
+}
+
+export const DEFAULTS: LoopConfig = {
+	maxRounds: 12,
+	maxStrikes: 2,
+	injectState: true,
+	maxInjectedTasks: 6,
+};
+
+export type DecisionInput = {
+	/** `turn_end` outcome: "completed" is the only value that may continue. */
+	outcome: string;
+	/** Number of tool results in the turn that just ended. */
+	toolResultCount: number;
+	/** Current task signature (id:status joined), empty when no list. */
+	signature: string;
+	/** Open (pending or in_progress) task count. */
+	openCount: number;
+	/** Total tracked task count, used only for the stop reason. */
+	taskCount: number;
+	/** Id of the newest human message on the branch. */
+	anchor: string;
+	state: LoopState;
+	config: LoopConfig;
+};
+
+export interface Decision {
+	/** True when the caller should request another turn. */
+	continue: boolean;
+	/** True when the caller should persist `rounds` as they are (no reset). */
+	next: LoopState;
+	reason: string;
+}
+
+/**
+ * A stop keeps the counters. Only a new human message starts a new budget: a cap
+ * or strike stop that cleared them would re-arm the full budget on the next
+ * `turn_end` under the same anchor (another extension's continuation, a provider
+ * retry). A queued human message is a new anchor by definition, so it resets the
+ * budget the ordinary way.
+ */
+function stop(state: LoopState, reason: string): Decision {
+	return { continue: false, next: { ...state }, reason };
+}
+
+/**
+ * Decide whether to continue.
+ *
+ * Order matters: a new human message resets the budget before anything else, so
+ * a long conversation cannot inherit the previous turn's spent rounds.
+ */
+export function decide(input: DecisionInput): Decision {
+	const { state, config } = input;
+
+	// A new human message owns a fresh budget.
+	let current: LoopState =
+		input.anchor !== state.anchor
+			? { ...state, rounds: 0, strikes: 0, lastSignature: "", staleSettles: 0, anchor: input.anchor }
+			: { ...state };
+
+	if (input.outcome !== "completed") {
+		return stop(current, `stopped: turn outcome was ${input.outcome}`);
+	}
+	if (input.openCount === 0) {
+		return stop(current, input.taskCount > 0 ? "stopped: list is clear" : "stopped: no list");
+	}
+
+	const progressed = input.toolResultCount > 0 || input.signature !== current.lastSignature;
+	if (progressed) {
+		current.strikes = 0;
+		current.staleSettles = 0;
+	} else {
+		current.staleSettles += 1;
+		// A budget must never read above the cap it is measured against (`strikes 3/2`).
+		current.strikes = Math.min(current.strikes + 1, config.maxStrikes);
+		if (current.strikes >= config.maxStrikes) {
+			return stop(
+				current,
+				`stopped: ${current.strikes} consecutive turns with no progress, ${input.openCount} open`,
+			);
+		}
+	}
+
+	if (current.rounds >= config.maxRounds) {
+		const stale =
+			current.staleSettles >= 2 ? `, list unchanged for ${current.staleSettles} settles` : "";
+		return stop(current, `stopped: round cap ${config.maxRounds} reached, ${input.openCount} open${stale}`);
+	}
+
+	current.rounds += 1;
+	current.lastSignature = input.signature;
+	return {
+		continue: true,
+		next: current,
+		reason: `continuing: round ${current.rounds}/${config.maxRounds}, ${input.openCount} open`,
+	};
+}
+
+export function initialState(): LoopState {
+	return { rounds: 0, strikes: 0, lastSignature: "", staleSettles: 0, anchor: "" };
+}