@brettinternet/pi-loop 0.1.2 → 0.1.3

package/README.md

@@ -12,19 +12,21 @@ pi install npm:@brettinternet/pi-loop
 /loop <count>
 /loop +<count>
 /loop -<count>
+/loop time <duration>
 /loop delay <duration>
 /loop prompt <text>
 /loop append <text>
 /loop status
 /loop
+/loop pause
 /loop end
 /loop resume
 /loop next
 ```
 
-Durations use `ms`, `s`, `m`, `h`, or `d`. Delays range from 1 second to 24 hours. Timed loops run for at most 30 days.
+Durations use `ms`, `s`, `m`, `h`, or `d`. Delays range from 1 second to 24 hours. Timed loops run for at most 30 days. During a loop, `/loop time <duration>` switches to a deadline from now or resets the current deadline; timed mode requires a non-zero delay. `/loop <count>` switches back to a count of future iterations.
 
-Errors retry after 30 seconds, 1 minute, and 2 minutes, then pause. Aborting pauses the loop. A `loop_pause` request pauses for human blockers. Recovery preserves the loop so you can resume or advance it.
+Errors retry after 30 seconds, 1 minute, and 2 minutes, then pause. Aborting pauses the loop. `/loop pause` pauses after the active iteration settles; if the loop is between iterations, it pauses immediately. Resuming then starts the next iteration. An agent `loop_pause` request pauses mid-iteration for human blockers, and resuming continues that iteration. Recovery preserves the loop so you can resume or advance it.
 
 Chain commands in the prompt:
 

package/index.ts

@@ -12,7 +12,7 @@ import { Type } from "typebox";
 export const LOOP_STATE_ENTRY = "pi-loop-state-v1";
 export const LOOP_WIDGET_KEY = "pi-loop";
 export const LOOP_USAGE =
-  "usage: /loop <positive-count> [--delay <duration>] <prompt> | /loop for <duration> --delay <duration> <prompt> | /loop <positive-count> | /loop <+|-><count> | /loop delay <duration> | /loop prompt <text> | /loop append <text> | /loop status | /loop resume | /loop next | /loop end";
+  "usage: /loop <positive-count> [--delay <duration>] <prompt> | /loop for <duration> --delay <duration> <prompt> | /loop <positive-count> | /loop <+|-><count> | /loop time <duration> | /loop delay <duration> | /loop prompt <text> | /loop append <text> | /loop status | /loop pause | /loop resume | /loop next | /loop end";
 
 export const MIN_LOOP_DELAY_MS = 1_000;
 export const MAX_LOOP_DELAY_MS = 24 * 60 * 60 * 1_000;
@@ -26,7 +26,7 @@ const LOOP_AGENT_GUIDANCE = `## Active Loop
 
 This session is part of an active unattended loop. If no useful work can continue without human input, credentials, permissions, or another non-transient external dependency, call loop_pause with the blocker. Do not pause for a temporary condition expected to resolve in a later iteration.`;
 
-export type LoopStatus = "active" | "stopping" | "paused" | "completed" | "stopped" | "inactive";
+export type LoopStatus = "active" | "pausing" | "stopping" | "paused" | "completed" | "stopped" | "inactive";
 export type LoopPhase = "running" | "waiting" | "retrying";
 
 export interface LoopState {
@@ -54,18 +54,20 @@ export type ParsedLoopCommand =
   | { kind: "startTimed"; duration: number; delay: number; prompt: string }
   | { kind: "retune"; count: number }
   | { kind: "adjust"; delta: number }
+  | { kind: "time"; duration: number }
   | { kind: "delay"; delay: number }
   | { kind: "replacePrompt"; prompt: string }
   | { kind: "appendPrompt"; prompt: string }
   | { kind: "status" }
+  | { kind: "pauseAtBoundary" }
   | { kind: "resume" }
   | { kind: "next" }
   | { kind: "end" }
   | { kind: "continue"; runId: string; iteration: number }
   | { kind: "pause"; runId: string; iteration: number };
 
-const ACTIVE_STATUSES = new Set<LoopStatus>(["active", "stopping"]);
-const VISIBLE_STATUSES = new Set<LoopStatus>(["active", "stopping", "paused"]);
+const ACTIVE_STATUSES = new Set<LoopStatus>(["active", "pausing", "stopping"]);
+const VISIBLE_STATUSES = new Set<LoopStatus>(["active", "pausing", "stopping", "paused"]);
 const TERMINAL_STATUSES = new Set<LoopStatus>(["completed", "stopped", "inactive"]);
 
 type ArgumentCompletion = { value: string; label: string; description?: string };
@@ -100,6 +102,15 @@ function completeLoopArguments(prefix: string): ArgumentCompletion[] | null {
   const delayCommand = /^(delay|--delay)(?:\s+(.*))?$/.exec(input);
   if (delayCommand?.[2] !== undefined) return delayCompletions(prefix, delayCommand[1]);
 
+  const timeCommand = /^time(?:\s+(.*))?$/.exec(input);
+  if (timeCommand?.[1] !== undefined) {
+    return completeArguments(timeCommand[1], COMMON_LOOP_TIMEFRAMES.map((value) => ({
+      value: `time ${value}`,
+      label: `time ${value}`,
+      description: "Switch to timed mode or reset the remaining time",
+    })));
+  }
+
   const timedDelay = /^for\s+(\S+)\s+--delay(=|\s+)?(.*)$/.exec(input);
   if (timedDelay) {
     if (timedDelay[2] !== undefined) {
@@ -164,9 +175,11 @@ function completeLoopArguments(prefix: string): ArgumentCompletion[] | null {
 
   return completeArguments(prefix, [
     { value: "status", label: "status", description: "Show the current loop state" },
-    { value: "resume", label: "resume", description: "Retry a paused iteration" },
+    { value: "pause", label: "pause", description: "Pause after the active iteration settles" },
+    { value: "resume", label: "resume", description: "Resume a paused loop" },
     { value: "next", label: "next", description: "Skip a paused iteration and start the next one" },
     { value: "end", label: "end", description: "End the loop gracefully" },
+    { value: "time ", label: "time <duration>", description: "Switch to timed mode or reset the remaining time" },
     { value: "delay ", label: "delay <duration>", description: "Set the delay between settled iterations" },
     { value: "prompt ", label: "prompt <text>", description: "Replace the future loop prompt" },
     { value: "append ", label: "append <text>", description: "Append to the future loop prompt" },
@@ -255,6 +268,10 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
     if (rest) throw new Error(`end does not accept arguments; ${LOOP_USAGE}`);
     return { kind: "end" };
   }
+  if (first === "pause") {
+    if (rest) throw new Error(`pause does not accept arguments; ${LOOP_USAGE}`);
+    return { kind: "pauseAtBoundary" };
+  }
   if (first === "resume") {
     if (rest) throw new Error(`resume does not accept arguments; ${LOOP_USAGE}`);
     return { kind: "resume" };
@@ -263,6 +280,11 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
     if (rest) throw new Error(`next does not accept arguments; ${LOOP_USAGE}`);
     return { kind: "next" };
   }
+  if (first === "time") {
+    const fields = rest.split(/\s+/).filter(Boolean);
+    if (fields.length !== 1) throw new Error(`time requires one duration; ${LOOP_USAGE}`);
+    return { kind: "time", duration: parseLoopTimeframe(fields[0]) };
+  }
   if (first === "delay") {
     const fields = rest.split(/\s+/).filter(Boolean);
     if (fields.length !== 1) throw new Error(`delay requires one duration; ${LOOP_USAGE}`);
@@ -352,6 +374,7 @@ export function parseLoopState(value: unknown): LoopState | undefined {
   const status = value.status;
   if (
     status !== "active" &&
+    status !== "pausing" &&
     status !== "stopping" &&
     status !== "paused" &&
     status !== "completed" &&
@@ -523,12 +546,13 @@ export function formatLoopWidget(state: LoopState, width: number, now = Date.now
   const retries = (state.retryCount ?? 0) > 0
     ? ` · retry ${state.retryCount}/${DEFAULT_LOOP_RETRIES}`
     : "";
-  if (state.status === "stopping") {
-    return truncateToWidth(`loop stopping${timeframe}${delay}${retries} · ${prompt}`, width, "…");
+  const iteration = state.endsAt === undefined ? "" : ` · #${state.currentIteration}`;
+  if (state.status === "pausing" || state.status === "stopping") {
+    return truncateToWidth(`loop ${state.status}${iteration}${timeframe}${delay}${retries} · ${prompt}`, width, "…");
   }
   if (state.endsAt !== undefined) {
     return truncateToWidth(
-      `loop ${state.status}${timeframe}${delay}${retries} · ${prompt}`,
+      `loop ${state.status}${iteration}${timeframe}${delay}${retries} · ${prompt}`,
       width,
       "…",
     );
@@ -572,6 +596,16 @@ export default function loopExtension(pi: ExtensionAPI): void {
   let commandInterruptedKey: string | undefined;
   let pendingFailure: PendingFailure | undefined;
   let currentSessionManagerRef: unknown;
+  let herdrBlocked = false;
+
+  function reportHerdrBlocked(state: LoopState | undefined): void {
+    const blocked = state?.status === "paused";
+    if (blocked === herdrBlocked) return;
+    herdrBlocked = blocked;
+    pi.events.emit("herdr:blocked", blocked
+      ? { active: true, label: `Loop paused: ${state.pauseReason ?? "human input required"}`, scope: "root" }
+      : { active: false, scope: "root" });
+  }
 
   function stateFrom(ctx: ContextWithSession): LoopState | undefined {
     runState = latestStateFromContext(ctx);
@@ -581,6 +615,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
   function persist(ctx: Pick<ExtensionAPI, "appendEntry">, state: LoopState): void {
     ctx.appendEntry(LOOP_STATE_ENTRY, state);
     runState = state;
+    reportHerdrBlocked(state);
   }
 
   function notify(ctx: ExtensionContext, message: string, type: "info" | "warning" | "error" = "info"): void {
@@ -602,6 +637,8 @@ export default function loopExtension(pi: ExtensionAPI): void {
       ctx.ui.setWidget(LOOP_WIDGET_KEY, [formatLoopWidget(state, Number.MAX_SAFE_INTEGER)], { placement: "belowEditor" });
       return;
     }
+    // Replacing the widget invalidates Pi's parent layout caches. Requesting a
+    // render alone can leave the previous line visible until another UI event.
     ctx.ui.setWidget(LOOP_WIDGET_KEY, (_tui, _theme) => ({
       render: (width) => [formatLoopWidget(state, width)],
       invalidate: () => {},
@@ -625,8 +662,11 @@ export default function loopExtension(pi: ExtensionAPI): void {
     }
     if (currentSessionManagerRef !== undefined && sessionManager !== currentSessionManagerRef) return undefined;
     const loaded = stateFrom(ctx);
-    if (!loaded) return undefined;
-    if (!stateBelongsToContext(loaded, ctx)) return undefined;
+    if (!loaded || !stateBelongsToContext(loaded, ctx)) {
+      reportHerdrBlocked(undefined);
+      return undefined;
+    }
+    reportHerdrBlocked(loaded);
     return loaded;
   }
 
@@ -679,7 +719,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
   ): void {
     if (!statusIsActive(state) || transitionInFlight) return;
     const nextBudget = state.pendingRetune ?? state.remainingBudget;
-    if (state.status === "stopping" || (state.endsAt === undefined && nextBudget <= 0) || state.delay === 0) {
+    if (state.status === "pausing" || state.status === "stopping" || (state.endsAt === undefined && nextBudget <= 0) || state.delay === 0) {
       clearContinuationWait();
       dispatchContinuation(ctx, state);
       return;
@@ -971,6 +1011,27 @@ export default function loopExtension(pi: ExtensionAPI): void {
     clearContinuationWait();
     clearRetryWait();
 
+    if (state.status === "pausing") {
+      const {
+        nextActionAt: _nextActionAt,
+        pauseReason: _pauseReason,
+        ...withoutSchedule
+      } = state;
+      const paused: LoopState = {
+        ...withoutSchedule,
+        status: "paused",
+        phase: "waiting",
+        settledAt: Date.now(),
+        pauseReason: "paused by user",
+        pausedAt: Date.now(),
+      };
+      persist(pi, paused);
+      renderWidget(ctx, paused);
+      runState = paused;
+      notify(ctx, "loop paused", "info");
+      return;
+    }
+
     if (state.status === "stopping") {
       const stopped = { ...state, status: "stopped" as const };
       persist(pi, stopped);
@@ -1075,6 +1136,41 @@ export default function loopExtension(pi: ExtensionAPI): void {
       return;
     }
 
+    if (parsed.kind === "time") {
+      if (!state || isTerminal(state)) {
+        notify(ctx, "a loop must be active, stopping, or paused to update its remaining time", "error");
+        return;
+      }
+      if (state.delay === 0) {
+        notify(ctx, "timed loops require a non-zero delay; set /loop delay <duration> first", "error");
+        return;
+      }
+      const switchingModes = state.endsAt === undefined;
+      const endsAt = Date.now() + parsed.duration;
+      const nextActionAt = state.phase === "waiting" && state.nextActionAt !== undefined
+        ? Math.min((state.settledAt ?? state.nextActionAt - state.delay) + state.delay, endsAt)
+        : state.nextActionAt;
+      const updated = {
+        ...state,
+        remainingBudget: 0,
+        pendingRetune: null,
+        endsAt,
+        ...(nextActionAt !== undefined ? { nextActionAt } : {}),
+      };
+      persist(pi, updated);
+      renderWidget(ctx, updated);
+      if (state.status === "active") rescheduleContinuation(ctx, updated);
+      const duration = formatLoopDelay(parsed.duration);
+      if (state.status === "paused") {
+        notify(ctx, `loop ${switchingModes ? `changed to timed mode with ${duration} left` : `time left set to ${duration}`}; resume will use it`, "info");
+      } else if (state.status === "stopping") {
+        notify(ctx, `loop ${switchingModes ? `changed to timed mode with ${duration} left` : `time left set to ${duration}`}; loop is still stopping`, "info");
+      } else {
+        notify(ctx, switchingModes ? `loop changed to timed mode with ${duration} left` : `loop time left set to ${duration}`, "info");
+      }
+      return;
+    }
+
     if (parsed.kind === "delay") {
       if (!state || isTerminal(state)) {
         notify(ctx, "a loop must be active, stopping, or paused to update its delay", "error");
@@ -1108,6 +1204,35 @@ export default function loopExtension(pi: ExtensionAPI): void {
       return;
     }
 
+    if (parsed.kind === "pauseAtBoundary") {
+      if (!state || isTerminal(state)) {
+        notify(ctx, "a loop must be active to pause", "error");
+        return;
+      }
+      if (state.status === "paused") {
+        notify(ctx, "loop is already paused", "info");
+        return;
+      }
+      if (state.status === "pausing") {
+        notify(ctx, "loop will pause after the active iteration", "info");
+        return;
+      }
+      if (state.phase === "retrying") {
+        pauseLoop(ctx, state, "paused by user");
+        notify(ctx, "loop paused", "info");
+        return;
+      }
+      const pausing: LoopState = { ...state, status: "pausing" };
+      persist(pi, pausing);
+      renderWidget(ctx, pausing);
+      if (state.phase === "waiting") {
+        await advanceAtBoundary(ctx, pausing.runId, pausing.currentIteration);
+        return;
+      }
+      notify(ctx, "loop will pause after the active iteration", "info");
+      return;
+    }
+
     if (parsed.kind === "end") {
       if (!state || state.status === "inactive" || state.status === "completed" || state.status === "stopped") {
         notify(ctx, "loop: no active run", "info");
@@ -1145,7 +1270,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
     }
 
     if (parsed.kind === "resume") {
-      if (state?.status === "stopping") {
+      if (state?.status === "pausing" || state?.status === "stopping") {
         const resumed = { ...state, status: "active" as const };
         persist(pi, resumed);
         renderWidget(ctx, resumed);
@@ -1160,6 +1285,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
         await advanceAtBoundary(ctx, state.runId, state.currentIteration, true);
         return;
       }
+      const pausedAtBoundary = state.phase === "waiting";
       const {
         pauseReason: _pauseReason,
         pausedAt: _pausedAt,
@@ -1176,7 +1302,11 @@ export default function loopExtension(pi: ExtensionAPI): void {
       persist(pi, resumed);
       renderWidget(ctx, resumed);
       handledSettlementKey = undefined;
-      continueCurrentIteration(ctx, resumed);
+      if (pausedAtBoundary) {
+        await advanceAtBoundary(ctx, resumed.runId, resumed.currentIteration);
+      } else {
+        continueCurrentIteration(ctx, resumed);
+      }
       return;
     }
 
@@ -1214,12 +1344,18 @@ export default function loopExtension(pi: ExtensionAPI): void {
     }
 
     if (parsed.kind === "retune" || parsed.kind === "adjust") {
-      if (!state || (state.status !== "active" && state.status !== "stopping")) {
-        notify(ctx, "a loop must be active to retune its remaining budget", "error");
+      const canRetune = state && (
+        state.status === "active" ||
+        state.status === "stopping" ||
+        (parsed.kind === "retune" && state.status === "paused")
+      );
+      if (!canRetune) {
+        notify(ctx, "a loop must be active, stopping, or paused to retune its remaining budget", "error");
         return;
       }
-      if (state.endsAt !== undefined) {
-        notify(ctx, "a timed loop has no iteration budget to retune", "error");
+      const switchingModes = state.endsAt !== undefined;
+      if (switchingModes && parsed.kind === "adjust") {
+        notify(ctx, "a timed loop has no iteration budget to adjust; use /loop <positive-count> to switch modes", "error");
         return;
       }
       const currentBudget = state.pendingRetune ?? state.remainingBudget;
@@ -1228,11 +1364,20 @@ export default function loopExtension(pi: ExtensionAPI): void {
         notify(ctx, `cannot subtract more than the ${currentBudget} future iteration${currentBudget === 1 ? "" : "s"}`, "error");
         return;
       }
-      const retuned = { ...state, pendingRetune: nextBudget, status: "active" as const };
+      const { endsAt: _endsAt, ...withoutDeadline } = state;
+      const retuned = {
+        ...withoutDeadline,
+        pendingRetune: nextBudget,
+        status: state.status === "paused" ? "paused" as const : "active" as const,
+      };
       persist(pi, retuned);
       renderWidget(ctx, retuned);
-      if (nextBudget <= 0) rescheduleContinuation(ctx, retuned);
-      notify(ctx, `loop will run ${nextBudget} future iteration${nextBudget === 1 ? "" : "s"}`, "info");
+      if (switchingModes || nextBudget <= 0) rescheduleContinuation(ctx, retuned);
+      if (state.status === "paused") {
+        notify(ctx, `loop ${switchingModes ? "changed to" : "set to"} ${nextBudget} future iteration${nextBudget === 1 ? "" : "s"}; resume will use it`, "info");
+      } else {
+        notify(ctx, `loop ${switchingModes ? "changed to" : "will run"} ${nextBudget} future iteration${nextBudget === 1 ? "" : "s"}`, "info");
+      }
       return;
     }
 
@@ -1309,6 +1454,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
     const loaded = latestStateFromContext(ctx);
     const owned = loaded && stateBelongsToContext(loaded, ctx) ? loaded : undefined;
     runState = owned;
+    reportHerdrBlocked(owned);
     if (!owned || owned.status === "inactive") clearWidget(ctx);
     else renderWidget(ctx, owned);
     // New-session setup writes transferred state after this event and starts
@@ -1387,6 +1533,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
     const loaded = latestStateFromContext(ctx);
     const owned = loaded && stateBelongsToContext(loaded, ctx) ? loaded : undefined;
     runState = owned;
+    reportHerdrBlocked(owned);
     if (!owned || owned.status === "inactive") clearWidget(ctx);
     else renderWidget(ctx, owned);
     if (owned && statusIsActive(owned)) scheduleStartupRecovery(ctx, owned);
@@ -1406,6 +1553,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
         // Shutdown may already have detached the runtime's append action.
       }
     }
+    reportHerdrBlocked(undefined);
     clearWidget(ctx);
     currentSessionManagerRef = undefined;
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brettinternet/pi-loop",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Run a prompt repeatedly in fresh Pi sessions",
   "type": "module",
   "license": "MIT",