@hank-warren/pi-loop 0.8.0 → 1.0.0

package/src/inline-command.ts

@@ -1,159 +0,0 @@
-/**
- * Inline slash-command detection.
- *
- * Pi dispatches extension commands only when a message *starts* with the
- * command token; a command mentioned mid-prompt arrives as plain text. This
- * helper finds inline occurrences of a `/cmd` token (and `cmd:` prefix lines)
- * so the caller can react — here, by appending a reminder that tells the model
- * to invoke the corresponding tool. It never rewrites or re-sends the user's
- * message.
- *
- * Ported from @hank-warren/pi-goal, which proved the mechanism before pi-loop
- * absorbed it; the helper was always generic over the command name.
- */
-
-export interface InlineCommandSplit {
-	/** Text before the command token, trailing whitespace removed. */
-	prose: string;
-	/** Everything after the command token to end of message, trimmed. */
-	commandArgs: string;
-}
-
-/**
- * Find the first inline `/<commandName>` occurrence in `text`.
- *
- * Detection rules:
- * - The token must be preceded by start-of-line or whitespace and followed by
- *   whitespace plus a non-empty remainder. A bare trailing `/cmd` mention or a
- *   path-like `foo/cmd` never matches.
- * - A token at position 0 is ignored: that is Pi's native dispatch position.
- * - Occurrences inside backtick code (inline spans and fenced blocks) or
- *   inside a single/double-quoted span are ignored. Code regions are
- *   approximated by the CommonMark backtick-run rule: a run of N backticks
- *   opens a region closed by the next run of exactly N backticks.
- *
- * Returns undefined when no qualifying occurrence exists.
- */
-export function extractInlineCommand(
-	text: string,
-	commandName: string,
-): InlineCommandSplit | undefined {
-	const token = `/${commandName}`;
-	const ignored = ignoredRegions(text);
-	let searchFrom = 0;
-	while (searchFrom < text.length) {
-		const index = text.indexOf(token, searchFrom);
-		if (index === -1) return undefined;
-		searchFrom = index + 1;
-		if (index === 0) continue;
-		const before = text[index - 1];
-		if (before !== undefined && !/\s/.test(before)) continue;
-		const afterToken = text[index + token.length];
-		if (afterToken === undefined || !/\s/.test(afterToken)) continue;
-		if (insideRegion(ignored, index)) continue;
-		const commandArgs = text.slice(index + token.length).trim();
-		if (!commandArgs) continue;
-		return {
-			prose: text.slice(0, index).trimEnd(),
-			commandArgs,
-		};
-	}
-	return undefined;
-}
-
-/**
- * True when the message inline-invokes the command: a mid-message `/cmd`
- * token with a remainder, or a `cmd:` prefix at the start of any line — both
- * outside backtick code and quoted spans.
- */
-export function detectsInlineInvocation(text: string, commandName: string): boolean {
-	if (extractInlineCommand(text, commandName) !== undefined) return true;
-	const ignored = ignoredRegions(text);
-	const prefixPattern = new RegExp(`^[ \\t]*${escapeRegExpText(commandName)}:[ \\t]+\\S`, "gim");
-	for (
-		let match = prefixPattern.exec(text);
-		match;
-		match = prefixPattern.exec(text)
-	) {
-		if (!insideRegion(ignored, match.index)) return true;
-	}
-	return false;
-}
-
-type Region = readonly [start: number, end: number];
-
-/**
- * Backtick code regions plus single/double-quoted spans. Quoting a command is
- * how people discuss one (`use "/loop 10m ship it" to start`), so a quoted
- * token is a mention, not an invocation.
- */
-function ignoredRegions(text: string): Region[] {
-	return [...codeRegions(text), ...quoteRegions(text)];
-}
-
-function codeRegions(text: string): Region[] {
-	const regions: Region[] = [];
-	const runs: Array<{ index: number; length: number }> = [];
-	const runPattern = /`+/g;
-	for (let match = runPattern.exec(text); match; match = runPattern.exec(text)) {
-		runs.push({ index: match.index, length: match[0].length });
-	}
-	for (let open = 0; open < runs.length; open += 1) {
-		const opener = runs[open];
-		if (opener === undefined) continue;
-		for (let close = open + 1; close < runs.length; close += 1) {
-			const closer = runs[close];
-			if (closer === undefined || closer.length !== opener.length) continue;
-			regions.push([opener.index, closer.index + closer.length]);
-			open = close;
-			break;
-		}
-	}
-	return regions;
-}
-
-/**
- * Single- and double-quoted spans, matched conservatively so an apostrophe
- * inside a word (`don't`) never opens one: an opening quote follows nothing,
- * whitespace, or an opening bracket and precedes a non-space; its closing
- * quote is on the same line, follows a non-space, and precedes end-of-line,
- * whitespace, or closing punctuation.
- */
-function quoteRegions(text: string): Region[] {
-	const regions: Region[] = [];
-	for (let index = 0; index < text.length; index += 1) {
-		const quote = text[index];
-		if (quote !== '"' && quote !== "'") continue;
-		const before = text[index - 1];
-		const after = text[index + 1];
-		if (before !== undefined && !/[\s([{<]/.test(before)) continue;
-		if (after === undefined || /\s/.test(after)) continue;
-		const close = closingQuoteIndex(text, index, quote);
-		if (close === undefined) continue;
-		regions.push([index, close + 1]);
-		index = close;
-	}
-	return regions;
-}
-
-function closingQuoteIndex(text: string, openIndex: number, quote: string): number | undefined {
-	for (let index = openIndex + 1; index < text.length; index += 1) {
-		const char = text[index];
-		if (char === "\n") return undefined;
-		if (char !== quote) continue;
-		const before = text[index - 1];
-		const after = text[index + 1];
-		if (before === undefined || /\s/.test(before)) continue;
-		if (after !== undefined && !/[\s.,;:!?)\]}>]/.test(after)) continue;
-		return index;
-	}
-	return undefined;
-}
-
-function insideRegion(regions: readonly Region[], index: number): boolean {
-	return regions.some(([start, end]) => index >= start && index < end);
-}
-
-function escapeRegExpText(value: string) {
-	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}

package/src/inline-invocation.ts

@@ -1,109 +0,0 @@
-/**
- * Inline `/loop` invocation, tool-mediated.
- *
- * Pi only dispatches `/loop` when it starts the message. When the user writes
- * `quick check /loop 10m get CI green` or a `loop:` prefixed line mid-prompt,
- * this module appends a one-turn reminder to the system prompt so the model
- * reliably calls the `loop_start` tool with the objective. The user's message
- * itself is never touched — no cutting, splitting, re-sending, or visible
- * annotation — so there are no delivery races, no message loss, and no
- * transcript noise: guidance is injected at agent-start time, not by
- * rewriting input.
- *
- * Two hooks cooperate because neither alone is safe:
- * - `input` carries a `source` and so can tell user-typed text from
- *   extension-sent prompts, but any transform it returns rewrites the stored,
- *   visible user message. It only records the armed text here.
- * - `before_agent_start` can extend the system prompt, but fires for
- *   extension-sent prompts too, and pi-loop's own kickoff and continuation
- *   prompts contain phrases like "the active /loop objective" that the
- *   detector would match. It injects only when the starting prompt *is* the
- *   armed user message, and disarms on every start, matched or not.
- *
- * Two deliberate limits keep the armed window one turn wide:
- * - Streaming-typed input (`streamingBehavior` set, i.e. steered or queued)
- *   never arms. Pi returns from `prompt()` before `before_agent_start` for
- *   those, so an armed flag would survive to a later, unrelated turn — the
- *   window through which pi-loop's own continuation prompts could be matched.
- * - The hint is a per-turn `systemPrompt` append, not a stored message, so
- *   "call loop_start now" cannot linger in the conversation and fire on a
- *   later turn.
- *
- * The armed flag is also the `loop_start` tool's gate: unlike pi-goal, which
- * relied on prompt guidelines alone, a loop is self-continuing, so this
- * extension *enforces* that the tool only runs on a turn the user explicitly
- * invoked. See `InlineInvocationState.invokedThisTurn`.
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { detectsInlineInvocation } from "./inline-command.js";
-import type { LoopController } from "./loop.js";
-
-export const INLINE_LOOP_COMMAND = "loop";
-
-export const INLINE_LOOP_HINT =
-	"<system-reminder>The user's message this turn inline-invoked a loop (/loop or loop:). Call the loop_start tool now with the objective text that follows the token in that message, then begin working toward it. Do not answer the objective as prose without starting the loop. If the message is discussing, quoting, or documenting the /loop command rather than invoking it, do not call loop_start. This reminder applies only to the user's message this turn.</system-reminder>";
-
-/**
- * The armed state, shared between the hooks and the `loop_start` tool.
- *
- * `invokedThisTurn` is the hard gate: set when `before_agent_start` matched
- * the armed user message, cleared at `agent_end` and at every session
- * boundary. `loop_start` refuses whenever it is false, so no amount of prompt
- * drift, transcript replay, or model initiative can start a self-continuing
- * loop the user did not ask for.
- */
-export class InlineInvocationState {
-	invokedThisTurn = false;
-}
-
-export function registerInlineInvocation(
-	pi: ExtensionAPI,
-	controller: LoopController,
-	state: InlineInvocationState,
-) {
-	let armedText: string | undefined;
-
-	pi.on("input", (event) => {
-		// Extension-sourced messages (loop kickoffs, continuations, pokes, other
-		// extensions' injections) never arm the hint.
-		if (event.source === "extension") return;
-		// Steered or queued input returns from prompt() without ever reaching
-		// before_agent_start, so arming it would leave stale text armed.
-		if (event.streamingBehavior !== undefined) return;
-		if (!controller.settings.inlineInvocation) return;
-		if (!detectsInlineInvocation(event.text, INLINE_LOOP_COMMAND)) return;
-		armedText = event.text;
-	});
-
-	pi.on("before_agent_start", (event) => {
-		const armed = armedText;
-		armedText = undefined;
-		// Every start closes the previous turn's window, so a turn that ends
-		// without an agent_end still cannot leave the tool unlocked.
-		state.invokedThisTurn = false;
-		if (armed === undefined) return;
-		if (!controller.settings.inlineInvocation) return;
-		if (!promptCarriesArmedMessage(event.prompt, armed)) return;
-		state.invokedThisTurn = true;
-		return { systemPrompt: `${event.systemPrompt}\n\n${INLINE_LOOP_HINT}` };
-	});
-
-	const disarm = () => {
-		armedText = undefined;
-		state.invokedThisTurn = false;
-	};
-	pi.on("agent_end", disarm);
-	pi.on("session_start", disarm);
-	pi.on("session_shutdown", disarm);
-}
-
-/**
- * True when the starting prompt is the armed user message. Pi may wrap the
- * text with expanded prefixes or suffixes, so the armed text has to be the
- * whole prompt or one of its ends — mirroring how upstream recognises its own
- * owned prompts at a terminal boundary.
- */
-function promptCarriesArmedMessage(prompt: string, armed: string) {
-	return prompt === armed || prompt.startsWith(armed) || prompt.endsWith(armed);
-}

package/src/start-tool.ts

@@ -1,199 +0,0 @@
-/**
- * `loop_start`: the model-invoked way into a loop.
- *
- * Pi only dispatches `/loop` when it starts the message, so a mid-prompt
- * `quick check /loop 10m get CI green` arrives as ordinary prose. The
- * inline-invocation hooks append a one-turn reminder to the system prompt for
- * exactly that message, and this tool is what the reminder points at. It
- * reuses `LoopController.startLoop`, the same path the `/loop` command takes,
- * so replacement rules, the loop_complete availability guard, the ledger, the
- * kickoff anchor, and persistence all behave identically.
- *
- * The hard armed-gate is the deliberate divergence from pi-goal's equivalent
- * tool, which relied on prompt guidelines alone. A loop is *self-continuing*:
- * a spurious start does not produce one unwanted answer, it produces turns
- * until a cap. So the tool refuses outright unless the inline hint armed for
- * the turn that is calling it.
- *
- * The one thing this path may decide that the `/loop` command cannot is the
- * loop's completion criteria. They are otherwise a deterministic split of the
- * objective's grammar, which turns a context sentence into a gate criterion;
- * a model that read the objective can do better. It is accepted only *here*,
- * at start, before any work exists to grade and with the user seeing the
- * criteria echoed back — the point where the incentive to write an easy gate
- * is weakest. After start they are immutable, exactly as a derived set is.
- *
- * Registered unconditionally, like the other loop tools: the tool set is part
- * of the cached request prefix, so it never changes with loop state.
- */
-
-import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { LOOP_COMPLETE_TOOL } from "./complete-tool.js";
-import { formatDuration, parseDuration, parseInterval } from "./interval.js";
-import { MAX_CRITERIA, MAX_DESCRIPTION_LENGTH } from "./ledger.js";
-import type { InlineInvocationState } from "./inline-invocation.js";
-import type { LoopController } from "./loop.js";
-
-export const LOOP_START_TOOL = "loop_start";
-
-/** Long enough for a real objective, short enough to reject a pasted file. */
-const MAX_OBJECTIVE_LENGTH = 4_000;
-
-export function registerLoopStartTool(
-	pi: ExtensionAPI,
-	controller: LoopController,
-	invocation: InlineInvocationState,
-) {
-	pi.registerTool(
-		defineTool({
-			name: LOOP_START_TOOL,
-			label: "Loop Start",
-			description:
-				"Start a /loop for an objective the user explicitly invoked with an inline /loop or loop: token in their message. Only for explicit invocations: never start a loop from general conversation, your own initiative, or an instruction that merely sounds loop-like. The objective is the text following the token.",
-			promptSnippet:
-				"Start a /loop when the user's message contains an explicit inline /loop or loop: invocation",
-			promptGuidelines: [
-				"Call loop_start only when the user's message contains an explicit `/loop <objective>` or `loop: <objective>` token. Never start a loop without that token, no matter how loop-like the request sounds; the tool refuses when the turn carries no inline invocation.",
-				"If the user is discussing, quoting, or documenting the /loop command rather than invoking it — asking how it works, pasting a transcript, or editing text that mentions it — do not call loop_start.",
-				"Pass the objective text that follows the token, without the token itself. A leading interval (`10m`, `2h`) and flags like `--max 5` or `--expires 3d` become the interval, max, and expires parameters, not part of the objective.",
-				"Call loop_start before doing any of the objective's work, then continue working toward it in the same turn.",
-				"Leave the criteria parameter out by default: the extension splits the objective into completion criteria on its own (bullets, else sentences, else the whole objective). Propose criteria only when that split would misfire — when the objective mixes requirements with context sentences (`fix CI. it has been red since Tuesday.`), or packs several requirements into one sentence.",
-				"Every criterion you propose must be a faithful restatement of something the user asked for: never fewer, weaker, or easier than the objective as typed, and never a requirement they did not state. They are echoed back to the user at start and frozen afterwards — you may only ever flip a criterion's passes field.",
-				"When in doubt, omit criteria and let the deterministic split stand.",
-				"Never call loop_complete in the same turn as loop_start: the starting turn has not done the work, and completion needs cited evidence per criterion.",
-				"Before your first loop_start this session, read the pi-loop skill: the objective is split into the completion criteria this loop will be gated on, so its wording is the leverage point.",
-			],
-			parameters: Type.Object({
-				objective: Type.String({
-					minLength: 1,
-					maxLength: MAX_OBJECTIVE_LENGTH,
-					description:
-						"The loop objective, including how the loop knows it is done: the user's text following the /loop or loop: token, verbatim, without the token, the interval, or flags.",
-				}),
-				interval: Type.Optional(
-					Type.String({
-						description:
-							"Fallback wake interval from the invocation, e.g. '10m' or '2h'. Omit when the user named none.",
-					}),
-				),
-				max: Type.Optional(
-					Type.Integer({
-						minimum: 1,
-						description:
-							"Cap on the turns the loop causes (continuations and pokes), from a --max flag in the invocation.",
-					}),
-				),
-				expires: Type.Optional(
-					Type.String({
-						description: "Loop lifetime from an --expires flag in the invocation, e.g. '3d'.",
-					}),
-				),
-				criteria: Type.Optional(
-					Type.Array(
-						Type.String({ minLength: 1, maxLength: MAX_DESCRIPTION_LENGTH }),
-						{
-							minItems: 1,
-							maxItems: MAX_CRITERIA,
-							description:
-								"Optional completion criteria for this loop, each one checkable requirement restated faithfully from the user's objective. Replaces the deterministic split of the objective, so omit it unless that split would misfire.",
-						},
-					),
-				),
-			}),
-			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-				// The gate. Everything below is ordinary validation; this is the
-				// one check that makes a self-continuing tool safe to expose.
-				if (!invocation.invokedThisTurn) {
-					return refusal(
-						`${LOOP_START_TOOL} is only available on a turn whose user message contains an explicit inline /loop or loop: invocation. This turn has none, so no loop was started. If the user wants one, they can type /loop <interval> <objective>.`,
-						{},
-					);
-				}
-				const objective = params.objective.trim();
-				if (!objective) {
-					return refusal("Loop not started: the objective is empty.", {});
-				}
-				const criteria = params.criteria?.map((description) => description.trim());
-				const badCriteria = criteria && describeBadCriteria(criteria);
-				if (badCriteria) {
-					return refusal(
-						`Loop not started: ${badCriteria}. Pass one short checkable requirement per entry, or omit criteria to split the objective deterministically.`,
-						{ objective },
-					);
-				}
-				const existing = controller.state;
-				if (existing && existing.status !== "stopped") {
-					return refusal(
-						`Loop not started: a loop already exists in this session (${existing.status}). The user can replace it with /loop, or stop it with /loop stop.`,
-						{ existingLoopId: existing.id },
-					);
-				}
-				const intervalToken = params.interval?.trim() || controller.settings.defaultInterval;
-				const interval = parseInterval(intervalToken);
-				if (!interval) {
-					return refusal(
-						`Loop not started: invalid interval ${intervalToken}. Use <number><unit> with unit s, m, h, or d, e.g. 10m.`,
-						{ objective },
-					);
-				}
-				let expiresInMs: number | undefined;
-				if (params.expires !== undefined) {
-					expiresInMs = parseDuration(params.expires.trim());
-					if (expiresInMs === undefined) {
-						return refusal(
-							`Loop not started: invalid expiry ${params.expires}. Use <number><unit> with unit s, m, h, or d, e.g. 3d.`,
-							{ objective },
-						);
-					}
-				}
-				const result = controller.startLoop(ctx, {
-					kind: "start",
-					requestedMs: interval.requestedMs,
-					intervalMs: interval.effectiveMs,
-					clamped: interval.clamped,
-					...(params.max === undefined ? {} : { maxTurns: params.max }),
-					...(expiresInMs === undefined ? {} : { expiresInMs }),
-					...(criteria === undefined ? {} : { criteria }),
-					prompt: objective,
-				});
-				if (!result.ok) return refusal(`Loop not started: ${result.message}`, { objective });
-				const loop = result.loop;
-				return {
-					content: toolContent(
-						`Loop started (loop_id ${loop.id}): ${objective}. Fallback wake every ${formatDuration(loop.intervalMs)}. Keep working the objective this turn; the loop continues at every idle boundary until you call ${LOOP_COMPLETE_TOOL} with this loop_id and cited evidence for every criterion, a cap is reached, or the user stops it. Do not call ${LOOP_COMPLETE_TOOL} in this turn.`,
-					),
-					details: { loopId: loop.id, objective, intervalMs: loop.intervalMs },
-				};
-			},
-		}),
-	);
-}
-
-/**
- * Why a proposed criteria list cannot be used, or undefined when it can.
- *
- * A list that says nothing is worse than no list: it would replace the
- * deterministic split with a gate the model wrote and can pass by saying
- * anything. So a malformed list refuses the start rather than falling back
- * silently, which would leave the model believing its criteria were accepted.
- */
-function describeBadCriteria(criteria: readonly string[]): string | undefined {
-	if (criteria.length === 0) return "the criteria list is empty";
-	if (criteria.length > MAX_CRITERIA) {
-		return `a loop takes at most ${MAX_CRITERIA} criteria and ${criteria.length} were given`;
-	}
-	if (criteria.some((description) => !description)) return "one of the criteria is blank";
-	if (criteria.some((description) => description.length > MAX_DESCRIPTION_LENGTH)) {
-		return `a criterion may be at most ${MAX_DESCRIPTION_LENGTH} characters`;
-	}
-	return undefined;
-}
-
-function refusal(text: string, details: Record<string, unknown>) {
-	return { content: toolContent(text), details, isError: true };
-}
-
-function toolContent(text: string) {
-	return [{ type: "text" as const, text }];
-}