@brettinternet/pi-loop 0.1.3 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # pi-loop
 
-Run a prompt repeatedly, with a fresh session for every iteration.
+Run a prompt repeatedly, with a fresh session for every iteration. Each new session uses the model selected in the preceding session (including a custom non-default model); changing models mid-loop takes effect on the next iteration. If that model is unavailable, the loop pauses rather than falling back to the default.
 
 ```bash
 pi install npm:@brettinternet/pi-loop
@@ -26,6 +26,8 @@ pi install npm:@brettinternet/pi-loop
 
 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.
 
+A pending `/wait` or `until` watch keeps the current iteration's session alive until its wake-up turn settles (or it is cancelled). A paused wait or recurring watch holds the iteration until resumed or completed. Use `/loop delay` for a simple fixed gap between iterations; use `/wait` for a same-session follow-up and `until` for a condition that might become true earlier than a fixed deadline.
+
 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:
@@ -35,3 +37,11 @@ Chain commands in the prompt:
 ```
 
 Built-in interactive commands cannot be chained.
+
+While a loop is active, every child command receives its stable run ID as `PI_LOOP_RUN_ID`:
+
+```text
+PI_LOOP_RUN_ID=3992f183-e054-4068-a13e-11281d1747e2
+```
+
+The value is always the full UUID, remains unchanged across every iteration and replacement session in that loop, and differs between independent loops. When the loop ends or its session closes, pi-loop restores the previous value or removes the variable if it was previously unset.

package/index.ts

@@ -11,6 +11,7 @@ import { Type } from "typebox";
 
 export const LOOP_STATE_ENTRY = "pi-loop-state-v1";
 export const LOOP_WIDGET_KEY = "pi-loop";
+export const LOOP_RUN_ID_ENV = "PI_LOOP_RUN_ID";
 export const LOOP_USAGE =
   "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";
 
@@ -47,6 +48,7 @@ export interface LoopState {
   pausedAt?: number;
   ownerSessionId?: string;
   ownerSessionFile?: string;
+  model?: { provider: string; id: string };
 }
 
 export type ParsedLoopCommand =
@@ -64,12 +66,41 @@ export type ParsedLoopCommand =
   | { kind: "next" }
   | { kind: "end" }
   | { kind: "continue"; runId: string; iteration: number }
-  | { kind: "pause"; runId: string; iteration: number };
+  | { kind: "pause"; runId: string; iteration: number }
+  | { kind: "restoreModel"; runId: string; iteration: number };
 
 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"]);
 
+const LOOP_ENVIRONMENT_STATE_KEY = "__piLoopRunEnvironmentV1";
+type LoopEnvironmentState = { runId: string; originalValue: string | undefined };
+
+function environmentState(): LoopEnvironmentState | undefined {
+  return (globalThis as Record<string, unknown>)[LOOP_ENVIRONMENT_STATE_KEY] as LoopEnvironmentState | undefined;
+}
+
+function exposeLoopRunId(runId: string): void {
+  const active = environmentState();
+  if (active) {
+    active.runId = runId;
+  } else {
+    (globalThis as Record<string, unknown>)[LOOP_ENVIRONMENT_STATE_KEY] = {
+      runId,
+      originalValue: process.env[LOOP_RUN_ID_ENV],
+    } satisfies LoopEnvironmentState;
+  }
+  process.env[LOOP_RUN_ID_ENV] = runId;
+}
+
+function restoreLoopRunId(expectedRunId?: string): void {
+  const active = environmentState();
+  if (!active || (expectedRunId !== undefined && active.runId !== expectedRunId)) return;
+  if (active.originalValue === undefined) delete process.env[LOOP_RUN_ID_ENV];
+  else process.env[LOOP_RUN_ID_ENV] = active.originalValue;
+  delete (globalThis as Record<string, unknown>)[LOOP_ENVIRONMENT_STATE_KEY];
+}
+
 type ArgumentCompletion = { value: string; label: string; description?: string };
 
 function completeArguments(
@@ -312,7 +343,7 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
   // These commands are only emitted by the extension itself. Keeping them in
   // the same dispatcher gives boundary transitions command-only session APIs
   // while preventing user input from accidentally looking like one.
-  if (first === "__continue" || first === "__pause") {
+  if (first === "__continue" || first === "__pause" || first === "__restore_model") {
     const fields = rest.split(/\s+/).filter(Boolean);
     if (fields.length !== 2 || !/^[A-Za-z0-9_-]+$/.test(fields[0])) {
       throw new Error("invalid internal loop command");
@@ -323,7 +354,9 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
     }
     return first === "__continue"
       ? { kind: "continue", runId: fields[0], iteration }
-      : { kind: "pause", runId: fields[0], iteration };
+      : first === "__pause"
+        ? { kind: "pause", runId: fields[0], iteration }
+        : { kind: "restoreModel", runId: fields[0], iteration };
   }
 
   if (/^[+\-]\d/.test(first)) {
@@ -411,6 +444,12 @@ export function parseLoopState(value: unknown): LoopState | undefined {
   if (value.pausedAt !== undefined && !isNonNegativeInteger(value.pausedAt)) return undefined;
   if (value.ownerSessionId !== undefined && typeof value.ownerSessionId !== "string") return undefined;
   if (value.ownerSessionFile !== undefined && typeof value.ownerSessionFile !== "string") return undefined;
+  const model = value.model;
+  if (
+    model !== undefined &&
+    (!isRecord(model) || typeof model.provider !== "string" || !model.provider ||
+      typeof model.id !== "string" || !model.id)
+  ) return undefined;
 
   return {
     version: 1,
@@ -430,6 +469,9 @@ export function parseLoopState(value: unknown): LoopState | undefined {
     ...(value.pausedAt !== undefined ? { pausedAt: value.pausedAt } : {}),
     ...(value.ownerSessionId ? { ownerSessionId: value.ownerSessionId } : {}),
     ...(value.ownerSessionFile ? { ownerSessionFile: value.ownerSessionFile } : {}),
+    ...(isRecord(model) && typeof model.provider === "string" && typeof model.id === "string"
+      ? { model: { provider: model.provider, id: model.id } }
+      : {}),
   };
 }
 
@@ -597,6 +639,24 @@ export default function loopExtension(pi: ExtensionAPI): void {
   let pendingFailure: PendingFailure | undefined;
   let currentSessionManagerRef: unknown;
   let herdrBlocked = false;
+  const pendingWakes = new Map<string, boolean>();
+  let waitingForWake = false;
+  let wakeContext: ExtensionContext | undefined;
+
+  for (const channel of ["pi-until:busy", "pi-wait:busy"]) {
+    pi.events.on(channel, (value) => {
+      if (typeof value !== "boolean") return;
+      pendingWakes.set(channel, value);
+      if (!waitingForWake || [...pendingWakes.values()].some(Boolean)) return;
+      const ctx = wakeContext;
+      if (!ctx || !ctx.isIdle()) return;
+      const state = currentState(ctx);
+      if (!state || !statusIsActive(state) || transitionInFlight) return;
+      waitingForWake = false;
+      handledSettlementKey = stateKey(ctx, state);
+      scheduleContinuation(ctx, state);
+    });
+  }
 
   function reportHerdrBlocked(state: LoopState | undefined): void {
     const blocked = state?.status === "paused";
@@ -612,9 +672,19 @@ export default function loopExtension(pi: ExtensionAPI): void {
     return runState;
   }
 
+  function syncLoopEnvironment(state: LoopState | undefined): void {
+    const runId = state?.runId;
+    if (state && statusIsVisible(state)) {
+      exposeLoopRunId(state.runId);
+      return;
+    }
+    if (!transitionInFlight) restoreLoopRunId(runId);
+  }
+
   function persist(ctx: Pick<ExtensionAPI, "appendEntry">, state: LoopState): void {
     ctx.appendEntry(LOOP_STATE_ENTRY, state);
     runState = state;
+    syncLoopEnvironment(state);
     reportHerdrBlocked(state);
   }
 
@@ -885,6 +955,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
 
   function transferState(state: LoopState, manager: SessionManager): LoopState {
     const transferred = stateForSession({ ...state, status: "active" }, sessionIdentity(manager));
+    exposeLoopRunId(transferred.runId);
     manager.appendCustomEntry(LOOP_STATE_ENTRY, transferred);
     return transferred;
   }
@@ -893,9 +964,17 @@ export default function loopExtension(pi: ExtensionAPI): void {
     replacement: ReplacementContext,
     state: LoopState,
   ): Promise<void> {
-    // The new extension instance restores this entry in before_agent_start.
-    // This callback still owns the command context, so it is the safe place to
-    // start the turn after the replacement is complete.
+    // The replacement owns the new extension runtime. Restore its model before
+    // starting a turn, rather than using the invalidated previous runtime.
+    if (state.model) {
+      await replacement.sendUserMessage(
+        `/loop __restore_model ${state.runId} ${state.currentIteration}`,
+        { expandPromptTemplates: true },
+      );
+      if (replacement.model?.provider !== state.model.provider || replacement.model.id !== state.model.id) {
+        throw new Error(`loop model unavailable: ${state.model.provider}/${state.model.id}`);
+      }
+    }
     if (replacement.hasUI) showWidget(replacement, state);
     if (state.endsAt !== undefined && Date.now() >= state.endsAt) {
       await replacement.sendUserMessage(
@@ -908,6 +987,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
   }
 
   async function replaceForIteration(ctx: ExtensionCommandContext, next: LoopState): Promise<void> {
+    exposeLoopRunId(next.runId);
     clearContinuationWait();
     clearRetryWait();
     clearRecoveryTimer();
@@ -1068,6 +1148,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
     } = state;
     const next: LoopState = {
       ...withoutPause,
+      ...(ctx.model ? { model: { provider: ctx.model.provider, id: ctx.model.id } } : {}),
       currentIteration: state.currentIteration + 1,
       remainingBudget: state.endsAt === undefined ? nextBudget - 1 : 0,
       pendingRetune: null,
@@ -1119,6 +1200,16 @@ export default function loopExtension(pi: ExtensionAPI): void {
       return;
     }
 
+    if (parsed.kind === "restoreModel") {
+      const state = currentState(ctx);
+      if (!state || state.runId !== parsed.runId || state.currentIteration !== parsed.iteration || !state.model) return;
+      const model = ctx.modelRegistry.find(state.model.provider, state.model.id);
+      if (!model || !(await pi.setModel(model))) {
+        throw new Error(`loop model unavailable: ${state.model.provider}/${state.model.id}`);
+      }
+      return;
+    }
+
     if (parsed.kind === "pause") {
       const state = currentState(ctx);
       if (!state || state.runId !== parsed.runId || state.currentIteration !== parsed.iteration || !statusIsActive(state)) return;
@@ -1402,6 +1493,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
       status: "active",
       retryCount: 0,
       phase: "running",
+      ...(ctx.model ? { model: { provider: ctx.model.provider, id: ctx.model.id } } : {}),
       ...(timed ? { endsAt: Date.now() + parsed.duration } : {}),
       ...(contextIdentity(ctx).id ? { ownerSessionId: contextIdentity(ctx).id } : {}),
       ...(contextIdentity(ctx).file ? { ownerSessionFile: contextIdentity(ctx).file } : {}),
@@ -1449,11 +1541,15 @@ export default function loopExtension(pi: ExtensionAPI): void {
     clearCommandInterruption();
     pendingFailure = undefined;
     currentSessionManagerRef = ctx.sessionManager;
+    pendingWakes.clear();
+    waitingForWake = false;
+    wakeContext = ctx;
     transitionInFlight = false;
     handledSettlementKey = undefined;
     const loaded = latestStateFromContext(ctx);
     const owned = loaded && stateBelongsToContext(loaded, ctx) ? loaded : undefined;
     runState = owned;
+    syncLoopEnvironment(owned);
     reportHerdrBlocked(owned);
     if (!owned || owned.status === "inactive") clearWidget(ctx);
     else renderWidget(ctx, owned);
@@ -1518,6 +1614,12 @@ export default function loopExtension(pi: ExtensionAPI): void {
       return;
     }
     if (handledSettlementKey === key) return;
+    if ([...pendingWakes.values()].some(Boolean)) {
+      waitingForWake = true;
+      wakeContext = ctx;
+      return;
+    }
+    waitingForWake = false;
     handledSettlementKey = key;
     scheduleContinuation(ctx, loaded);
   });
@@ -1529,10 +1631,14 @@ export default function loopExtension(pi: ExtensionAPI): void {
     clearCommandInterruption();
     pendingFailure = undefined;
     currentSessionManagerRef = ctx.sessionManager;
+    pendingWakes.clear();
+    waitingForWake = false;
+    wakeContext = ctx;
     handledSettlementKey = undefined;
     const loaded = latestStateFromContext(ctx);
     const owned = loaded && stateBelongsToContext(loaded, ctx) ? loaded : undefined;
     runState = owned;
+    syncLoopEnvironment(owned);
     reportHerdrBlocked(owned);
     if (!owned || owned.status === "inactive") clearWidget(ctx);
     else renderWidget(ctx, owned);
@@ -1553,9 +1659,13 @@ export default function loopExtension(pi: ExtensionAPI): void {
         // Shutdown may already have detached the runtime's append action.
       }
     }
+    if (event.reason !== "reload" && !transitionInFlight) restoreLoopRunId(loaded?.runId);
     reportHerdrBlocked(undefined);
     clearWidget(ctx);
     currentSessionManagerRef = undefined;
+    waitingForWake = false;
+    wakeContext = undefined;
+    pendingWakes.clear();
   });
 
   pi.registerCommand("loop", {

package/package.json

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