@hank-warren/pi-loop 0.9.0 → 1.1.0

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 }];
-}